3CX Automated Proxmox Deployment Guide

Overview

This guide covers the automated deployment of a 3CX PBX Virtual Machine on Proxmox VE. Utilizing Debian generic cloud images and Cloud-Init, this script provisions the compute resources, handles network configuration via DHCP, injects required installation scripts, and can optionally restore a 3CX backup silently.

Prerequisites

Before running the deployment script, ensure the below prerequisites:

  • Go to Datacenter -> Storage.
  • Select local and click Edit
  • In the Content dropdown, make sure the Snippets and Disk Image options are selected.

  • Root Access: You must be logged into the Proxmox node as root.
  • SSH Keys: An SSH keypair must exist on the Proxmox host (e.g., /root/.ssh/id_rsa).
  • Internet Access: The Proxmox node must be able to reach cloud.debian.org to download the base image.
  • DHCP Reservation: The target network must have a DHCP server with a reserved IP mapped to the MAC address defined in your configuration.

Note: The example above demonstrates a DHCP reservation in a WatchGuard environment. The exact interface and steps to configure a static MAC-to-IP binding will vary depending on your specific network equipment (e.g., pfSense, UniFi, FortiGate, or Windows Server). The core requirement remains the same: this static unique MAC address will be permanently bound to this reserved IP address on your network, and will be used in your .env file as described below in the Deploying your 3CX Phonesystem section.

Download the 3CX Proxmox Deployment Tools

  • Login through SSH (or the web management shel function) as root user into the Proxmox Host
  • Navigate to the home folder and download the 3CX deployment tools:

cd ~

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

tar -zxvf 3cx-proxmox.tar.gz

Deploying your 3CX Phonesystem

Prepare your deployment folder

  • Create a dedicated folder for your new PBX (in this example ~/3cx-proxmox/deployments/pbx01) and copy the environment template into it:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Note: If you are performing a silent restore, you must also copy your setupconfig.xml and 3cx-backup.zip files into this folder.

Configure your .ENV file

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

Pay attention to the following:

  • set PBX_INSTALLATION_MODE to "manual" (the default):
  • Option 1: create a valid ~/3cx-proxmox/deployments/pbx01/setupconfig.xml file
  • Option 2: alternatively, you can get a setupconfig.xml file already prepared with a valid minimal configuration from the 3CX Portal
  • if you are performing a restore. set BACKUP_FILE to the filename of your backup (inside ~/3cx-proxmox/deployments/pbx01)
  • set PBX_INSTALLATION_MODE to "wizard" to boot into the web UI setup
  • set VMID to an available unique Proxmox VM ID
  • you can check currently used VM IDs from the proxmox shell with qm list
  • DISK_GB (default 40)
  • CORES (default 2)
  • SOCKETS (default 1)
  • MEMORY_MB (default 2048)
  • set your MAC_ADDRESS to the value you set in the prerequisites stage above
  • (optional) set your VLAN_TAG (default empty)
  • set the desired 3CX Version variables; for the latest 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) set your SSH_PUBLIC_KEY_FILE and SSH_PRIVATE_KEY_FILE paths if you have created custom keys to secure communications between your proxmox host and guests

You can read more about Deploying 3CX and Provisioning Settings via setupconfig.xml

Project Directory Structure

This is what your directory structure should look like:

Run the deployment script

Execute the main script, passing the path to the specific environment file using the --config (or -c) flag:

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%)

Monitor the deployment

The script provides live terminal feedback. It will systematically:

  • Download the Debian cloud image (if not cached).
  • Dynamically inject your scripts and variables into a unique Cloud-Init snippet.
  • Provision the VM compute resources and network interface.
  • Start the VM and wait for the QEMU Guest Agent to report the assigned DHCP IP address.

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

Automated Setup and Handoff

Once the IP address is detected, the script automatically cleans your Proxmox known_hosts file to prevent SSH conflicts. It then securely copies the backup file (if provided) and executes the 3cx-setup.sh installation script remotely.

Upon completion, a success banner will be displayed with the VM's summary.

Post-Deployment Notes

Depending on the PBX_INSTALLATION_MODE chosen, the final steps will vary:

  • Wizard Mode: The script will poll the newly created VM until the 3CX Web Wizard becomes responsive. Once complete, navigate to http://<VM_IP>:5015 in your browser to finalize the setup.
  • Manual Mode: The PBX will silently install using the injected setupconfig.xml and optionally restore from the provided backup file. No further wizard interaction is required.

Note: Deployment logs can be found under configuration directory. For instance, ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

Get your setupconfig.xml file from the 3CX Portal

To get a pre-configured minimal setupconfig.xml file directly from the 3CX Portal:

  • Login to your 3CX Portal account

  • Identify your target system, and click the Install link

  • Select the On Premise options and click the Next button

  • Select the number of digits for your system's extensions and click the Next button

  • Select your regional preferences for your system and click the Next button

  • In the final page, select the Linux platform
  • Click the Download link to download a SetupConfig.xml file
  • rename the downloaded SetupConfig.xml to setupconfig.xml - the install scripts are case sensitive
  • Copy the setupconfig.xml file to your proxmox machine into ~/3cx-proxmox/deployments/pbx01/setupconfig.xml

Last Updated

This document was last updated 26 May 2026

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