VM Setup Script Description

This page is used as part of the VM Setup Guide and is informational only — normally not required for a standard VM setup.

Script coverage

In the tables below, you can find all configuration settings needed to set up the XCC and MTA VMs with their respective config files; if they are covered by the setup script, and whether the change is mandatory or optional. Each Setting / topic links to a detailed description of the configuration changes. If the step is covered by the setup script, it is not necessary to manually execute these steps again.

Setting / topic	Config files	Mandatory
Hostname	`GUI:/activeguard/core/active_guard.yml` `GUI:/activeguard/mta/audit/audit.yml` `GUI:/monitoring/grafana/grafana.ini` `GUI:/monitored_mta/promtail/config.yml.vmx.N` `/etc/xorlab/elastic/kibana/kibana.yml`	Yes
Bind IP	`/etc/xorlab/xcc/.env`	Yes
Proxy	`/etc/apt/apt.conf.d/proxy.conf` `/etc/systemd/system/docker.service.d/http-proxy.conf` `/etc/xorlab/xcc/backend/bootstrap.yml` `/etc/xorlab/auth/bootstrap.env` `/etc/xorlab/monitoring/bootstrap.env` `GUI:activeguard/core/active_guard.yml`	If proxies are used
EHLO	`GUI:activeguard/mta/startup_cfg/postfix_custom/main.cf.vmx.N`	Yes
Network	`/etc/netplan/00-xorlab-config.yaml`	If static IPs are used
Disk Resizing		Yes
NTP servers	`/etc/systemd/timesyncd.conf`	Optional
Resource Configuration	`/etc/xorlab/xcc/backend/backend.env` `/etc/xorlab/xcc/backend/backend.env` `GUI:xcc/backend/xcc.yml` `/etc/xorlab/elastic/docker-compose.yml` `/etc/xorlab/xcc/.env`	Yes
Locally Trusted Certificates	`/etc/xorlab/tls` `/etc/xorlab/xcc/backend/bootstrap.yml` `/activeguard/core/active_guard.yml` `/etc/xorlab/auth/bootstrap.env` `/etc/xorlab/monitoring/bootstrap.env` `/monitored_mta/promtail/config.yml` `/activeguard/mta/audit/audit.yml`	If locally trusted certificates are used
Firewall	`/etc/xorlab/firewall/iptables.service`	Optional

Setting / topic	Config files	Mandatory
Hostname	`/etc/xorlab/activeguard/.env`	Yes
Bind IP	`/etc/xorlab/activeguard/.env` `/etc/xorlab/rproxy_mta/.env` `/etc/xorlab/monitored_mta/.env`	Yes
XCC URL	`/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env` `/etc/xorlab/activeguard/.env`	Yes
Client ID	`/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env`	Yes
Proxy	`/etc/apt/apt.conf.d/proxy.conf` `/etc/systemd/system/docker.service.d/http-proxy.conf` `/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env`	If proxies are used
Network	`/etc/netplan/00-xorlab-config.yaml`	If static IPs are used
Disk Resizing		Yes
NTP servers	`/etc/systemd/timesyncd.conf`	Optional
Resource Configuration	`/etc/xorlab/activeguard/.env` `GUI:activeguard/mta/startup_cfg/postfix_custom/main.cf.vmx.N`	Yes
Locally Trusted Certificates	`/etc/xorlab/activeguard/bootstrap.env` `/etc/xorlab/rproxy_mta/bootstrap.env` `/etc/xorlab/monitored_mta/bootstrap.env`	If locally trusted certificates are used
Firewall	`/etc/xorlab/firewall/iptables.service`	Optional

Using the script

The first run of the script is always interactive. You answer a series of questions, inputting desired values, which you can save in the config file. Subsequent runs can be non-interactive, provided you have made changes directly in the config file. After setting the desired values, xorlab-setup offers to restart the services and Docker daemon. It then checks xorlab update and backend services. On MTA VMs, it also checks XCC reachability; on the XCC VM, it prompts for the MTA hostnames to check. xorlab-setup supports these switches:

--help prints the available switches and exits.
--restart-services restarts the xorlab services without changing configuration.
--reachability-test loads the saved /etc/xorlab/bootstrap_config when available and runs only the reachability checks.

Settings common to XCC and MTA that you can change:

hostname - sets the hostname on the VM itself (via hostnamectl) and updates all relevant entries in xorlab configuration files.
bind IP - the IP address of the interface to which xorlab stack components bind
proxy - APT, Docker daemon, bootstrap, and active_guard.yml proxies. PROXY_USER and PROXY_PASS are optional settings

MTA specific settings:

client ID - unique ID number of the MTA VM
XCC FQDN - fully qualified domain name (or hostname) of the XCC VM

Script outputs basic information about the changes being made, and logs them in more detail to the /var/log/xorlab/host/host_bootstrap.log. In the file you can find commands with arguments that the script executes. It should be the first place to look whenever there are problems, or the script does not execute properly. To see the log file, open it with less -R, more, tail, or other program which interprets colors. Config values entered by the user can be saved to a config file (/etc/xorlab/bootstrap_config), which also serves as a history of changes. The config generated on one MTA can then be copied to other MTAs, adjusted, and sourced by the script, without the need to give the same answers again. Reachability test prompts are transient and answers are not stored in /etc/xorlab/bootstrap_config. Enter optional internal service destinations as host or host:port. IPv6 literals are not supported; the script reports inputs containing more than one colon as invalid and skips the corresponding check.

Example config file

# [2026-02-26 14:41:14]
XCC_BIND_IP=192.168.1.100
XCC_HOSTNAME=new-xcc-hostname
TEMPLATE_DOMAIN=mx.example.com
MTA1_DOMAIN=mx1.example.com
MTA2_DOMAIN=mx2.example.com
SET_PROXY=y
PROXY_TYPE=HTTP
PROXY_HOST=proxyhost
PROXY_PORT=9876
PROXY_USER=proxyuser
PROXY_PASS="proxypassword"

Logic of the setup script

The initial setup of the VM and xorlab is done by running xorlab-setup. This is a wrapper which will execute the following steps:

Determine whether it is run on a XCC or an MTA VM.
When started without arguments, optionally update the actual setup script xorlab-set-up-[xcc|mta]. If the update process fails, or the update is skipped, a preinstalled local version will be run.
When started with arguments such as --help, --restart-services, or --reachability-test, skip the update prompt and forward the arguments directly to the local role-specific script.
Execute xorlab-set-up-xcc or xorlab-set-up-mta, depending on the VM type.

The following diagram depicts described logic:

The diagram is simplified. In current releases, the wrapper prompts for an update only when started without arguments. Argument-based invocations skip that prompt and call the local role-specific script directly.

Script breakdown

Hostname

Connect to the XCC VM

ssh admin@xcc.example.com

and set the new VM hostname.

sudo hostnamectl hostname new-xcc-hostname

Open /etc/xorlab/elastic/kibana/kibana.yml config, and set the server.publicBaseUrl:

(...)
# The public URL for end-users to access Kibana.
server.publicBaseUrl: https://new-xcc-hostname/insights
(...)

Open the Expert Editor, you will need to set new hostname value in these files:

activeguard/mta/audit/audit.yml

serviceProviders:
xcc:
    # Service provider definition, see documentation of active_guard.yml for details. There is a maximum of 1 XCC host allowed.
    hosts:
    # REPLACE before Go-Live
    - https://new-xcc-hostname:9080
    ssl:
    trustAll: true

monitoring/grafana/grafana.ini

instance_name = new-xcc-hostname

[paths]
data = /var/lib/grafana
logs = /var/log/grafana

[server]
protocol = http
domain = new-xcc-hostname
root_url = %(protocol)s://%(domain)s/monitoring/
(...)

monitored_mta/promtail/config.yml.vmx.N

(...)
clients:
# REPLACE before Go-Live
- url: https://new-xcc-hostname:3100/loki/api/v1/push
    tls_config:
    insecure_skip_verify: true
# - url: <OTHER-LOG-SINK>
(...)

activeguard/core/active_guard.yml

(...)
xcc:
  hosts:
    # REPLACE before Go-Live
    - https://new-xcc-hostname:9080
  ssl:
    trustAll: true
(...)

Deploy your changes by clicking the Publish button (1). In the pop-up window describe your changes (2), and press the Publish button (3) in the bottom right corner of the pop-up dialog. Publish pop-up window

Connect to the MTA VM

ssh admin@mta1.example.com

and set the new VM hostname.

sudo hostnamectl hostname new-mta1-hostname

Open the /etc/xorlab/activeguard/.env file, set the core_hostname to the hostname

(...)
# CORE_SPAMD_MIN_CHILD=5
core_hostname=new-mta1-hostname
CORE_JVM_ARGS=-Xmx6g
(...)

and restart the activeguard stack.

cd /etc/xorlab/activeguard/ && docker compose down && docker compose up -d

Repeat the steps for each MTA VM.

Bind IP

Connect to the XCC VM:

ssh admin@xcc.example.com

Enable browser access to the XCC web interface by opening the /etc/xorlab/xcc/.env file and changing the XCCWEB_BIND_IP variable to the IP that the XCC web interface should bind to:

XOR_REGISTRY=registry.xorlab.com
XCCWEB_BIND_IP=xxx.xxx.xxx.xxx
(...)

and restart the xcc stack.

cd /etc/xorlab/xcc && docker compose down && docker compose up -d

Connect to the MTA VM:

ssh admin@mta1.example.com

Open the /etc/xorlab/<STACK>/.env file for each stack (activeguard,rproxy_mta,monitored_mta) and change the BIND_IP variable to the IP that the service should bind to:

XOR_REGISTRY=registry.xorlab.com
BIND_IP=xxx.xxx.xxx.xxx
(...)

and restart the stack.

cd /etc/xorlab/<STACK> && docker compose down && docker compose up -d

Repeat the steps for each MTA VM.

Template Domain

Open /activeguard/core/active_guard.yml in the Expert Editor.
Set templateDomain to the domain that resolves via MX to all MTAs, as set in 2. step in DNS registration.

active_guard.yml

templateDomain: mx.example.com

Click Publish, then restart all MTAs. The templateDomain setting is in active_guard.yml and requires an MTA restart; see How to Activate the Configuration.

Trusted MTA Profiles

Open /activeguard/core/active_guard.yml in the Expert Editor.

Insert all MTA Fully Qualified Domain Names (A records) registered in the 1. step in DNS registration:

trustedMTAProfiles:
- name: default
  trusted:
    - hostNamePattern: mx1\.example\.com
    - hostNamePattern: mx2\.example\.com

Click Publish, then restart all MTAs. The trustedMTAProfiles setting is in active_guard.yml and requires an MTA restart; see How to Activate the Configuration.

Client ID

Connect to the MTA VM:

ssh admin@mta1.example.com

Open the /etc/xorlab/<STACK>/bootstrap.env file for each stack (activeguard,rproxy_mta,monitored_mta) and change the clientId variable to the number of the MTA VM:

# xorlab bootstrap configuration
licenseId=EXAMPLE
licenseKey=REDACTED

## Set to the MTA host number, e.g. clientId=2 for the 2nd MTA, and so on...
clientId=1
(...)

and restart the stack.

cd /etc/xorlab/<STACK> && docker compose down && docker compose up -d

Repeat the steps for each MTA VM.

XCC URL

Connect to the MTA VM:

ssh admin@mta1.example.com

Open the /etc/xorlab/activeguard/.env file, and change the redis_url variable to the Fully Qualified Domain Name or the Hostname of the XCC VM.

(...)
# Set address of xcc VM (hosting redis) here, e.g. xcc.example.com
redis_url=new-xcc-hostname

Open the /etc/xorlab/<STACK>/bootstrap.env file for each stack (activeguard,rproxy_mta,monitored_mta) and change the Fully Qualified Domain Name or the Hostname of the XCC VM in the configServiceProvider_ag_local variable:

(...)
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['https://new-xcc-hostname:9080'], 'ssl': {'trustAll': True}}}

and restart the stack.

cd /etc/xorlab/<STACK> && docker compose down && docker compose up -d

Repeat the steps for each MTA VM.

Proxy Configuration

If the xorlab can only connect to external servers through an HTTP proxy, you’ll need to execute the following steps:

Enable APT to pull OS updates
Enable the Docker daemon to pull new Docker images
Configure the XCC and MTA containers
Update active_guard.yml in the Expert Editor to enable SystemTests
If integrated, configure the VirusTotal service

Optional and mandatory proxy settingsUser (PROXY_USER) and password (PROXY_PASS) are optional, whereas type (PROXY_TYPE), port (PROXY_PORT), and host (PROXY_HOST) are mandatory across all the config files.

APT proxy

Connect to the XCC or MTA VM:

ssh admin@xcc.example.com

Open the /etc/apt/apt.conf.d/proxy.conf file:

vim /etc/apt/apt.conf.d/proxy.conf

uncomment the config, and provide your credentials to the proxy server:

Acquire::http::Proxy "http://user:password@proxy.example.com:port/";
Acquire::https::Proxy "http://user:password@proxy.example.com:port/";

Save the file. Test the configuration by executing the following command and verifying that no connection error appears:

sudo apt update && sudo apt upgrade

Repeat the steps for each MTA VM.

Docker Daemon proxy

The proxy for the Docker daemon is set using environment variables using systemd. XCC and MTA VMs come with prepared, commented out proxy configuration in the /etc/systemd/system/docker.service.d/http-proxy.conf. Connect to the XCC or MTA VM:

ssh admin@xcc.example.com

Uncomment config lines and replace the exemplary proxy values.

[Service]
Environment="HTTP_PROXY=http(s)://user:password@proxy.example.com:80"
Environment="HTTPS_PROXY=http(s)://user:password@proxy.example.com:443"
Environment="NO_PROXY=localhost,127.0.0.1/8,.xor"

# NOTE: Depending on your proxy configuration, the HTTPS_PROXY variable might also need to use http:// scheme.

Before proceeding, use docker compose down to shut down all running container stacks. Then reload the service configuration and restart the Docker service:

sudo systemctl daemon-reload && sudo systemctl restart docker

# Verify that the new environment settings were loaded:
sudo systemctl show docker --property Environment

Repeat the steps for each MTA VM.

ServiceProvider proxy

Configure the proxy used by containers for most outgoing connections, including downloading the latest global configuration, in the bootstrap files (bootstrap.yml and bootstrap.env). Connect to the XCC VM:

ssh admin@xcc.example.com

Open the bootstrap.env file in your favorite editor for the auth, monitoring and xcc stacks:

vim /etc/xorlab/<stack>/bootstrap.env

Uncomment configServiceURL_ag_global (line 12), uncomment configServiceProvider_ag_global (line 11) and add the value in the JSON format to use the corresponding proxy and xCloud:

## xorlab bootstrap configuration
licenseId=EXAMPLE
licenseKey=REDACTED


# Where to find the ConfigurationService (URL(s) where to find the ConfigService)
# e.g. "https://xcc.example.com:9080"
# e.g. "https://xcc.example.com:9080,https://fallback.example.com:9080"
# If a proxy for external connections is used, remove configServiceURL_ag_global and use configServiceProvider_ag_global
# If the proxy uses TLS inspection and provides an untrusted certificate, set 'trustAll' to 'True'
configServiceProvider_ag_global={"serviceProvider":{"hosts": ['https://xcloud.ch1.activeguard.io', 'https://xcloud.ch2.activeguard.io', 'https://xcloud.ch3.activeguard.io'], "proxy": {'type': 'HTTP', 'host': 'proxy.example.com', 'port': 8080, 'user': 'proxy_user', 'password': 'proxy_password'}, 'ssl': {'trustAll': False}}}
# configServiceURL_ag_global=https://xcloud.ch1.activeguard.io,https://xcloud.ch2.activeguard.io,https://xcloud.ch3.activeguard.io
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['http://backend.xcc.xor:9080'], 'ssl': {'trustAll': True}}}

Restart container stacks:

cd /etc/xorlab/<stack> && docker compose down && docker compose up -d

Connect to the MTA VM:

ssh admin@mta1.example.com

Open the bootstrap.env file in your favorite editor for the activeguard, monitored_mta, and rproxy_mta stacks:

vim /etc/xorlab/<stack>/bootstrap.env

Uncomment configServiceURL_ag_global (line 12), uncomment configServiceProvider_ag_global (line 11) and add the value in the JSON format to use the corresponding proxy and xCloud:

## xorlab bootstrap configuration
licenseId=EXAMPLE
licenseKey=REDACTED

## Set to the MTA host number, e.g. clientId=2 for the 2nd MTA, and so on...
clientId=1

# Where to find the ConfigurationService (URL(s) where to find the ConfigService)
# e.g. "https://xcc.example.com:9080"
# e.g. "https://xcc.example.com:9080,https://fallback.example.com:9080"
# If a proxy for external connections is used, remove configServiceURL_ag_global and use configServiceProvider_ag_global
# If the proxy uses TLS inspection and provides an untrusted certificate, set 'trustAll' to 'True'
configServiceProvider_ag_global={"serviceProvider":{"hosts": ['https://xcloud.ch1.activeguard.io', 'https://xcloud.ch2.activeguard.io', 'https://xcloud.ch3.activeguard.io'], "proxy": {'type': 'HTTP', 'host': 'proxy.example.com', 'port': 8080, 'user': 'proxy_user', 'password': 'proxy_password'}, 'ssl': {'trustAll': False}}}
# configServiceURL_ag_global=https://xcloud.ch1.activeguard.io,https://xcloud.ch2.activeguard.io,https://xcloud.ch3.activeguard.io
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['https://new-xcc-hostname:9080'], 'ssl': {'trustAll': True}}}

Restart container stacks:

cd /etc/xorlab/<stack> && docker compose down && docker compose up -d

Repeat the steps for each MTA VM.

xorlab Services and SystemTests

To enable connection to the xorlab backend services (DANA, xCloud, ML), open the Expert Editor and navigate to /activeguard/core/active_guard.yml. Here you can uncomment and set proxy values for each backend service.

(...)
## xorlab services
serviceProviders:
  xcloud:
    hosts:
      - https://xcloud.ch1.activeguard.io
      - https://xcloud.ch2.activeguard.io
      - https://xcloud.ch3.activeguard.io
    retryRequestCount: 1
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  xcc:
    hosts:
      - https://new-xcc-hostname:9080
    ssl:
      trustAll: true

  dana1.ch:
    hosts:
      - https://dana.ch1.activeguard.io
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  dana2.ch:
    hosts:
      - https://dana.ch2.activeguard.io
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  dana3.ch:
    hosts:
      - https://dana.ch3.activeguard.io
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  tika:
    hosts:
      - https://tika.ch1.activeguard.io
      - https://tika.ch2.activeguard.io
      - https://tika.ch3.activeguard.io
    retryRequestCount: 1
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
  ml:
    hosts:
      - https://ml1.ch.activeguard.io
      - https://ml2.ch.activeguard.io
    retryRequestCount: 1
    proxy:
      type: HTTP
      host: proxy.example.com
      port: 8080
      # user: proxy-user
      # password: proxy-password
(...)

There are two system tests that can use proxy: ReachXorlabSystemTest and URLRedirectFollowerSystemTest. In order to configure them, you need to insert the httpProxy block into /activeguard/core/active_guard.yml.

httpProxy:
  type: HTTP
  host: proxy.example.com
  port: 8080
  # user: proxy-user
  # password: proxy-password

Click Publish, then restart the activeguard stack on each MTA. These active_guard.yml service and proxy settings require an MTA restart; see How to Activate the Configuration.

​Script coverage

​Using the script

​Script breakdown

​Hostname

​Bind IP

​Template Domain

​Trusted MTA Profiles

​Client ID

​XCC URL

​Proxy Configuration

​APT proxy

​Docker Daemon proxy

​ServiceProvider proxy

​xorlab Services and SystemTests

Script coverage

Using the script

Script breakdown

Hostname

Bind IP

Template Domain

Trusted MTA Profiles

Client ID

XCC URL

Proxy Configuration

APT proxy

Docker Daemon proxy

ServiceProvider proxy

xorlab Services and SystemTests