This guide applies to installations on V18. If you are running on V20, follow this guide.

Deploying 3CX and Provisioning Settings via setupconfig.xml

Introduction

It is possible to launch and automatically configure 3CX by creating a pre-populated XML file with answers as input to the questions that the 3CX command-line tool asks you. You can place this XML file either in the host or in cloud-init, so 3CX parses it automatically and fully auto-configures your PBX in no time!

It is also possible to include extensions, SIP Trunks and DIDs during installation.

Overview

The deployment process with “setupconfig.xml” works by placing the XML file on the machine to automatically configure 3CX during install:

The process flow using setupconfig.xml to setup a 3CX PBX

  1. Download this sample Setup Template XML file.
  2. Modify the configuration in the XML file manually and fill in all required details.
  3. Place the setupconfig.xml file on the host machine:
  • For Linux in: “/etc/3cxpbx/setupconfig.xml”.
  • For Windows in: “C:\ProgramData\3CX\Data\setupconfig.xml”.
  1. Install 3CX. When 3CX is installed, the command line wizard checks the above locations for the XML file and if found, it is automatically processed.

Amazon AWS cloud-init

💡 Tip: Instead of copying the file you can also use cloud-init by copying the contents of the XML and paste it in the “Advanced” / “User data” section. Consider this example for Amazon AWS cloud-init.

Example of Cloud-init

To include “setupconfig.xml” in cloud-init, download and use this cloud-init sample:  

#!/bin/bash -e

mkdir -p /etc/3cxpbx

cat > /etc/3cxpbx/setupconfig.xml << "<EOF>"

<?xml version="1.0" encoding="utf-8"?>

 <!--PUT CONTENTS OF SETUPCONFIG.XML HERE-->

<EOF>

apt-get update

dpkg-query -W -f='${Status}' sudo 2>/dev/null | grep -qF "ok installed" || apt-get -y install sudo

dpkg-query -W -f='${Status}' wget 2>/dev/null | grep -qF "ok installed" || apt-get -y install wget

dpkg-query -W -f='${Status}' gnupg2 2>/dev/null | grep -qF "ok installed" || apt-get -y install gnupg2

wget -O- https://repo.3cx.com/key.pub | gpg --dearmor | sudo tee /usr/share/keyrings/3cx-archive-keyring.gpg > /dev/null

echo "deb [arch=$(dpkg --print-architecture) by-hash=yes signed-by=/usr/share/keyrings/3cx-archive-keyring.gpg] http://repo.3cx.com/3cx buster main" | sudo tee /etc/apt/sources.list.d/3cxpbx.list

apt-get update

apt-get -y install nginx

rm -f /etc/nginx/sites-enabled/default

systemctl reload nginx

apt-get -y install 3cxpbx

Setupconfig.xml Εxplained

The “setupconfig.xml” is split in these sections:

  1. <tcxinit> - Parameters for the initial phase of the PBX Configuration tool, e.g. license, backup file path, network settings, public IP, FQDN (3CX FQDN or Custom FQDN), hostname, local DNS, HTTP(S) ports, extension length, mail server, timezone, country and license info.
  2. <extensions> - Declare the extensions to create in this section.
  3. <siptrunk> - Define SIP trunks and DIDs to deploy here and add a subnode in <inboundrules> to create inbound routing associated with the DID of that SIP trunk.
  4. <OutboundRules> - Add outbound rules to create in this section.

Configuring the Wizard

This is a an example XML subset that corresponds to the questions asked in the First-time Configuration wizard:

   

<option> <code>NumberOfExtensions</code> <answer>3</answer> </option>

<option> <code>AdminEmail</code> <answer>[email protected]</answer> </option>

<option> <code>MailServerType</code> <answer>3CX</answer> </option>

<option> <code>MailServerAddress</code> <answer>smtp.example.com</answer> </option>

<option> <code>MailServerReplyTo</code> <answer>[email protected]</answer> </option>

<option> <code>MailServerUserName</code> <answer>username</answer> </option>

<option> <code>MailServerPassword</code> <answer>password</answer> </option>

<option> <code>MailServerEnableSslTls</code> <answer>yes</answer> </option>

<option> <code>Continent</code> <answer>North America</answer> </option>

<option> <code>Country</code> <answer>United States</answer> </option>

<option> <code>Timezone</code> <answer>9</answer> </option>

<option> <code>OperatorExtension</code> <answer>000</answer> </option>

<option> <code>OperatorFirstName</code> <answer>John</answer> </option>

<option> <code>OperatorLastName</code> <answer>Doe</answer> </option>

<option> <code>OperatorEmail</code> <answer>[email protected]</answer> </option>

<option> <code>OperatorVoicemail</code> <answer>999</answer> </option>

<option> <code>Promptset</code> <answer>English</answer> </option>

<option> <code>LicenseContactName</code> <answer>John L. Doe</answer> </option>

<option> <code>LicenseCompanyName</code> <answer>My Company Ltd.</answer> </option>

<option> <code>LicenseEmail</code> <answer>[email protected]</answer> </option>

<option> <code>LicensePhone</code> <answer>+357 99 87654321</answer> </option>

<option> <code>ResellerId</code><answer></answer> </option>

To populate “Country” and “Timezone” refer to this document and select values from the appropriate columns. For example, to specify “Mexico” based on the list you can use this configuration:

...

<option> <code>Country</code> <answer>Mexico</answer> </option>

<option> <code>Timezone</code> <answer>5</answer> </option>

...

Enabling the Hosting Admin Role

The hosting admin role in 3CX requires separate login credentials and once enabled the Hosting Admin can only see certain settings within the system. These settings are: Licence information, Network Configuration and Additional Parameters. Any other admin settings cannot be accessed from within the Hosting Admin user role.

During installation the system hoster needs to specify these values in the setupconfig.xml to deploy:

...

<HostingConfiguration>

        <HostingAdminLogin>admin_user</HostingAdminLogin>

        <HostingAdminPassword>Adm1n_P@$$</HostingAdminPassword>

        <HostingAdminEmail>[email protected]</HostingAdminEmail>

</HostingConfiguration>

...

Adding Extensions, SIP Trunks, DID’s and Outbound Rules

Use the “<extensions>” section to:

For example, to provision a Snom 720 phone, locate the model in the guide and note the corresponding supported codecs and template file name, i.e. “snom.ph.xml”. Enter this information in the corresponding XML tags in your “setupconfig.xml” file.

Creating an Extension

To automatically create and configure a new extension, add the info in an “<extension>” node under the “<extensions>” section:

...

<extension>

   <Number>000</Number>

   <FirstName>John</FirstName>

   <LastName>Smith</LastName>

   <EmailAddress>[email protected]</EmailAddress>

   <MobileNumber>801123456</MobileNumber>

   <OutboundCallerId>801123456</OutboundCallerId>

   <AuthPassword>extensionPassword</AuthPassword>

   <AuthID>000</AuthID>

   <AllowLanOnly>false</AllowLanOnly>

   <RecordCalls>false</RecordCalls>

   <TemplateFilename>snom.ph.xml</TemplateFilename>

   <ProvisioningFilename2>Snom 720</ProvisioningFilename2>

   <MAC>121212ABABAB</MAC>

   <Codecs>

      <codec>G711u</codec>

      <codec>G711a</codec>

      <codec>G722</codec>

      <codec>G729</codec>

   </Codecs>

   <Language>English</Language>

   <ProvisionType>LocalLan</ProvisionType>

   <AllowOwnRecordings>false</AllowOwnRecordings>

</extension>

...

Creating a SIP Trunk, DID’s and Inbound rules

To automatically create a SIP trunk, as well as its DIDs and inbound rules, declare the relevant info in a “<siptrunk>” node based on this XML example excerpt:

...

<siptrunk>

   <Name>Voip Trunk 1</Name>

   <TemplateFilename>GenericSIPTrunk.pv.xml</TemplateFilename>

   <Host>trunk.example.com</Host>

   <Port>5050</Port>

   <ProxyHost>proxy.trunk.example.com</ProxyHost>

   <ProxyPort>5160</ProxyPort>

   <SimultaneousCalls>10</SimultaneousCalls>

   <RequireRegistrationFor>InOutCalls</RequireRegistrationFor>

   <AuthID>369456456456</AuthID>

   <AuthPassword>sgh88DMVU6Uz60MQzwvF</AuthPassword>

   <Use3WayAuth>true</Use3WayAuth>

   <SeparateAuthPassword>3WayPass</SeparateAuthPassword>

   <ExternalNumber>0044870478519100</ExternalNumber>

   <OfficeHoursDestinationType>Extension</OfficeHoursDestinationType>

   <OfficeHoursDestination>100</OfficeHoursDestination>

   <OutOfOfficeHoursDestinationType>External</OutOfOfficeHoursDestinationType>

   <OutOfOfficeHoursDestination>96855555</OutOfOfficeHoursDestination>

   <DIDNumbers>0044870478519101,0044870478519102</DIDNumbers>

   <OutboundCallerID>0044870478519100</OutboundCallerID>

   <Direction>Both</Direction>

   <DeliverAudio>true</DeliverAudio>

   <DisableVideoCalls>true</DisableVideoCalls>

   <SupportReinvite>false</SupportReinvite>

   <SupportReplaces>false</SupportReplaces>

   <PublicIpInSipViaHeader>1.2.3.4</PublicIpInSipViaHeader>

   <EnableSRTP>false</EnableSRTP>

   <TimeBetweenReg>120</TimeBetweenReg>

   <IPInRegistrationContact>Default</IPInRegistrationContact>

   <SpecifiedIPForRegistrationContact></SpecifiedIPForRegistrationContact>

   <AlternativeProxy></AlternativeProxy>

   <TransportProtocol></TransportProtocol>

   <IPMode></IPMode>

   <Codecs>

      <codec>PCMU</codec>

      <codec>GSM</codec>

      <codec>iLBC</codec>

      <codec>G722</codec>

      <codec>opus</codec>

      <codec>G729</codec>

      <codec>PCMA</codec>

      <codec>Speex</codec>

   </Codecs>

   <InboundRules>

      <InboundRule>

         <Name>IncomingCall1</Name>

         <DID>0044870478519101</DID>

         <OfficeHoursDestinationType>Extension</OfficeHoursDestinationType>

         <OfficeHoursDestination>001</OfficeHoursDestination>

         <OutOfOfficeHoursDestinationType>VoiceMail</OutOfOfficeHoursDestinationType>

         <OutOfOfficeHoursDestination>001</OutOfOfficeHoursDestination>

         <SpecificHours>

            <HoursRange>

               <StartTime>08:00</StartTime>

               <EndTime>16:00</EndTime>

               <DayOfWeek>Monday</DayOfWeek>

            </HoursRange>

            <HoursRange>

               <StartTime>17:00</StartTime>

               <EndTime>22:00</EndTime>

               <DayOfWeek>Monday</DayOfWeek>

            </HoursRange>

         </SpecificHours>

      </InboundRule>

   </InboundRules>

</siptrunk>

...

Creating Outbound Rules with Backup Routes

In the “<OutboundRules>” section, you can add “<OutboundRule>” nodes to automatically create relevant outbound rules and backup routes via your setupconfig.xml:

...

<OutboundRules>

   <OutboundRule>

      <Name>Outbound Rule 1</Name>

      <Prefix>111</Prefix>

      <DNRanges>

         <DNRange>

            <To>000</To>

            <From>000</From>

         </DNRange>

         <DNRange>

            <To>100</To>

            <From>105</From>

         </DNRange>

      </DNRanges>

      <NumberLengthRanges>9,10,11</NumberLengthRanges>

      <DNGroups>

         <Group>Sales</Group>

         <Group>CEO</Group>

      </DNGroups>

      <OutboundRoutes>

         <OutboundRoute>

            <Gateway>GatewayIn</Gateway>

            <StripDigits>0</StripDigits>

            <Prepend>807</Prepend>

         </OutboundRoute>

         <OutboundRoute>

            <Gateway>Trunk1a</Gateway>

            <StripDigits>1</StripDigits>

            <Prepend>801</Prepend>

         </OutboundRoute>

      </OutboundRoutes>

   </OutboundRule>

</OutboundRules>

...

Importing SSL Certificates

To include SSL certificate information in your “setupconfig.xml”, consider this example to configure the parts relevant to SSL:

Importing SSL certificates via setupconfig.xml

📄 Note: Different types of certificates require different XML nodes to be configured. Though “CertificatePath” is used in all, “CertificatePassword” is used only for pfx.

See also

Last Updated

This document was last updated on 4 March 2024

https://www.3cx.com/docs/configure-pbx-automatically-v18/