VM Setup Script Description

Here you’ll find the manual steps required to set up the VMs, which are automated by the Setup Scripts.

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 Control Center UI by opening the /etc/xorlab/xcc/.env file and changing the XCCWEB_BIND_IP variable to the IP that the Control Center UI 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 MTA_BIND_IP variable to the IP that the service should bind to:

XOR_REGISTRY=registry.xorlab.com
XCCWEB_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.

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:

# XSP 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

Allow containers to download the latest global configuration through a proxy, by configuring proxy in the bootstrap files (bootstrap.yml, bootstrap.env). Connect to the XCC VM:

ssh admin@xcc.example.com

Open the bootstrap.yml file in your favorite editor for the backend stack:

vim /etc/xorlab/xcc/backend/bootstrap.yml

Set your proxy credentials, and uncomment used parameters. Note that this needs to be done only for the ag_global entry:

(...)
configServices:
## The repo name to retrieve from this service.
- repoName: ag_global
    ## Connection information for the config service (ServiceProvider config)
    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: some-user
    #   password: some-password
    (...)

Open the bootstrap.env file in your favorite editor for the auth and monitoring 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:

## XSP 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:

## XSP 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, NLU), 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

Publish the changes; the configuration will be applied after one minute. You can also manually restart the activeguard stack.

​Hostname

​Bind IP

​Client ID

​XCC URL

​Proxy Configuration

​APT proxy

​Docker Daemon proxy

​ServiceProvider proxy

​xorlab Services and SystemTests

Hostname

Bind IP

Client ID

XCC URL

Proxy Configuration

APT proxy

Docker Daemon proxy

ServiceProvider proxy

xorlab Services and SystemTests