Automatically configure 3CX with the setupconfig.xml response file

Published on February 11, 2017

Automatically configure 3CX with the setupconfig.xml response file

  • Tutorial


You can automatically install and configure the 3CX server using the prepared answer file. An answer file is an XML file that contains the same parameters that you specify on the command line or web interface of the 3CX Configuration Wizard. You can create such a file and place it directly on the server or cloud.init cloud image configuration package. For all the “questions” that are usually asked in the 3CX Setup Wizard, the system receives pre-set “answers” ​​from the file. As a result, in a few minutes you get a fully configured and ready-to-use system, configured according to your standard template. You can also include in the answer file the parameters of extension numbers, SIP trunks and DID lines, which will be automatically created during the configuration process.

Technology Overview


Prepare the XML file and place it on the server before starting the 3CX installation:

  1. Download sample XML response file setupconfig.xml
  2. Indicate in it the parameters corresponding to your configuration
  3. Save setupconfig.xml on the server in the appropriate folder:
    • For Linux version 3CX: /etc/3cxpbx/setupconfig.xml .
    • For Windows version 3CX: C: \ ProgramData \ 3CX \ Data \ setupconfig.xml

  4. When installing 3CX, the Initial Configuration Wizard checks for the presence of the setupconfig.xml file .

Instead of copying the file to the server, you can use cloud.init. Copy the contents of setupconfig.xml to the Advanced> User data section . The following is an example of an Amazon AWS cloud.init image.

Sample cloud.init file

Including setupconfig.xml in cloud.init .

→ Download an example cloud.init file

Setupconfig.xml file structure

The setupconfig.xml file is divided into 4 sections:

  • tcxinit - describes the initial stage of the PBX configuration wizard. It contains answers to such questions: license key or path to the backup file, network settings, public IP address, FQDN name (issued by 3CX or user name), host name, DNS type (local or from 3CX), HTTP / S ports and the like options.
  • mcwizard - describes the next step of the PBX configuration wizard. It contains answers to such questions: extension number, mail server settings, time zone, country and information about the owner of the 3CX system.
  • extensions - in this section parameters of extension numbers (users) are indicated.
  • siptrunk - in this section parameters of SIP trunks and DID numbers are indicated. The inboundrules subsections describe the inbound rules associated with the DID numbers of a specific trunk.
  • OutboundRules - This section describes the parameters for outbound rules.

Example: 3CX Initial Configuration Wizard answers

The 3CX Initial Configuration Wizard answer block is located in the mcwizard section :

For correct filling parameters CountryName , TimezoneId and LicenseCountry refer to the table and select the desired value. For example, for Mexico, specify the following parameters:

Example: adding extensions, SIP trunks, DIDs and outgoing rules

The extension , siptrunk , InboundRules, and OutboundRules response blocks define extension numbers, trunks, inbound and outbound rules, respectively. When describing an extension number, you can assign an IP phone to it. To do this, specify information on the auto-configuration templates for IP phones according to this table . For example, if you need to bind a snom 720 phone , look for this model and the corresponding auto- configuration template file in the table (in this case, ). Indicate this information in the corresponding xml tag.

Create Extension

Creating SIP Trunks, DIDs, and Inbound Rules

Creation of outgoing rules with indication of backup routes (trunks)

Example: automatic installation of SSL certificates

We show how to include SSL certificate data in the setupconfig.xml response file. This example deals only with the SSL certificate of the web server. For other certificates used by the system, add a description of the certificate in other sections of the response file. Way CertificatePath will be common to all, but the password for each certificate CertificatePassword   will be different.


3CX Downloads