VM Setup Guide

xorlab consists of two on-premises components: XCC and MTA. MTAs are email processing nodes that can be operated redundantly, depending on the expected load and availability requirements. XCC consolidates the analysis results from the MTAs and hosts the web interface. The optional setup of on-premises Sandbox (DANA) hardware is not covered by this page.

Preparation

Hardware requirements

XCC and the MTAs are provided as images in the OVF format. Our Sizing Guide will help you determine the right configuration for the resulting VMs. Download credentials can be requested via email.

Network requirements

Prepare your firewall and/or proxy such that the connections described in xorlab Network Guide are supported.

Unfiltered DNSMake sure your DNS service for xorlab is unfiltered. Otherwise, xorlab requests for malicious domains/IPs will not be answered and processed messages will be stuck in a queue because of DNS timeouts.

Register required DNS records

Register DNS A records for the XCC and MTA VMs with your internal DNS server(s). For XCC, you can also use a CNAME record instead of an A record. For the MTA VMs, A records are required; see also RFC 2181. The table below shows an example setup for example.com:
Component Record Type
XCC xcc.example.com A or CNAME
MTA1 mta1.example.com A
MTA2 mta2.example.com A

Component	Record	Type
XCC	`xcc.example.com`	A or CNAME
MTA1	`mta1.example.com`	A
MTA2	`mta2.example.com`	A

Add an MX record for every MTA in your setup. Use the same priority for all MTAs to achieve automatic load-balancing. In our example, we use mx.example.com and the DNS query result is:

dig MX mx.example.com
[...]
;; ANSWER SECTION:
mx.example.com. 3600    IN  MX  10 mta1.example.com.
mx.example.com. 3600    IN  MX  10 mta2.example.com.

Prepare the VMs

Download the XCC and MTA images (OVF format). The link and credentials will be provided by us.
Decompress the zip files and instantiate the XCC and MTA virtual machines using your Hypervisor.

Setup

Configure the network

The XCC and MTA VM images have DHCP configured on all network interfaces, which names match en*. If your environment requires static addresses, proceed with the steps below:

Open a shell on the VM using your hypervisor, log in and open the /etc/netplan/00-xorlab-config.yaml file with elevated privileges (sudo). Comment the dynamic configuration out, uncomment the static configuration, and set the appropriate values. In this example, for the ens192 interface, the config file should look like this:
network: version: 2 renderer: networkd ethernets: ens192: dhcp4: false dhcp6: false addresses: - 192.168.0.1/16 routes: - to: default via: 192.168.0.254 nameservers: search: - "example.com" addresses: - 192.168.0.254 - 192.168.0.253
Avoid using certain special-use domain namesSome special-use domain names can cause issues. For example, .local is reserved for multicast DNS (mDNS) and should not be used for private networks, since it can lead to name resolution conflicts. Instead, if you need a dedicated naming space for a local network, better use a subdomain under .home.arpa., which is specifically reserved for that purpose.

In case you want to add a second interface (or more) to your VM, you need to add a configuration for each:

Static IP configuration example for more interfaces

nameservers block can have either search or addresses, or both defined.

  version: 2
  renderer: networkd
  ethernets:
    ens192:
      dhcp4: false
      dhcp6: false
      addresses:
        - 192.168.0.1/16
      routes:
        - to: default
          via: 192.168.0.254
      nameservers:
        search:
          - "example.com"
        addresses:
          - 192.168.0.254
          - 192.168.0.253
    ens224:
      dhcp4: false
      dhcp6: false
      addresses:
        - 192.168.0.2/16
      routes:
        - to: default
          via: 192.168.0.254
      nameservers:
        search:
          - "example.com"
        addresses:
          - 192.168.0.254
          - 192.168.0.253

Apply the configuration by executing sudo netplan apply.
Restart all docker containers.

After changing the configuration on all your destination VMs, you should be able to connect to them using SSH.

Connect via SSH

All our virtual machines are running Ubuntu Linux. The OS comes with a pre-configured admin account. Use the credentials provided to you by xorlab to open an SSH connection.

Resize the disk

Now, resize the disks of the VMs so that they meet the requirements from the Sizing Guide:

Configure your hypervisor to provide the correct amount of storage to the VMs. This step is not described any further here since it depends on your hypervisor.
Execute the following steps on every xorlab VM (XCC and MTAs)

Run lsblk to show the current structure of the disks and partitions.

lsblk
NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda      8:0    0  100G  0 disk 
├─sda1   8:1    0    1M  0 part 
└─sda2   8:2    0  100G  0 part /

Run sudo fdisk /dev/<disk> - replace <disk> with the desired disk as shown before. Then follow the highlighted instructions below. The partition number might be different.

fdiskNo changes will be written to the disk before you execute the w command. You can accept the defaults by pressing the Enter key.

sudo fdisk /dev/sda
Command (m for help): p

Disk /dev/sda: 100 GiB, 107374182400 bytes, 209715200 sectors
Disk model: Virtual disk    
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 0E4A82CF-8961-476F-B565-F53F562FD9CE

Device     Start       End   Sectors  Size Type
/dev/sda1   2048      4095      2048    1M BIOS boot
/dev/sda2   4096 209713151 209709056  100G Linux filesystem

Command (m for help): d
Partition number (1,2, default 2): 

Partition 2 has been deleted.

Command (m for help): n
Partition number (2-128, default 2): 
First sector (4096-209715166, default 4096): 
Last sector, +/-sectors or +/-size{K,M,G,T,P} (4096-209715166, default 209715166): 

Created a new partition 2 of type 'Linux filesystem' and of size 100 GiB.
Partition #2 contains a ext4 signature.

Do you want to remove the signature? [Y]es/[N]o: n

Command (m for help): w

The partition table has been altered.
Syncing disks.

Resize the file system with:
sudo resize2fs /dev/sda2
Verify that the partition has the correct size with df -h.

Run the Setup Script

xorlab-setup will first determine the VM type it’s running on.

Connect to the XCC VM via SSH and run xorlab-setup.
Connect to the MTA VM via SSH and run xorlab-setup.

The script can be safely run multiple times. It logs additional information to /var/log/xorlab/host/host_bootstrap.log. When you invoke it without arguments, it offers to update to the newest wrapper-managed setup script version before starting the interactive set-up. Direct invocation with arguments such as --help, --restart-services, or --reachability-test omits the update prompt and forwards the arguments directly to the local role-specific script. Here you can find more information about the script:

Script Breakdown: Step-by-step instruction on what the script does. Use this in case you need to manually apply certain steps.
Script Coverage Overview: Overview of all config files changed by the script.
Script Usage: Save and re-use inputs to the setup script.

EHLO configuration

Set the hostnames used by the MTAs for the EHLO when the SMTP connection is established. For every xorlab MTA, you will see one main.cf.vmx.<id> file: main.cf.vmx.1 will be applied on MTA 1, main.cf.vmx.2 on MTA 2, and so on. If there is only one MTA, you will only find the main.cf file.

Open Expert Editor.
Navigate to the activeguard/mta/startup_cfg/postfix_custom/.
Edit each main.cf* file and set the myhostname parameter to the hostname that points to this MTA in your DNS (A record).

A sample activeguard/mta/startup_cfg/postfix_custom/main.cf file should look like this:

main.cf

# This hostname will be used by xorlab for SMTP, e.g. in the EHLO message
myhostname = mta1.example.com

Click Publish. The main.cf* changes become active within about one minute.

Set local NTP servers

xorlab uses the time provided by the OS. In order to configure the OS settings set the NTP line in /etc/systemd/timesyncd.conf:

[Time]
NTP=ntp.example.com ntp.ubuntu.com ...

Then restart the NTP service by executing:

sudo systemctl restart systemd-timesyncd.service

Configure performance resources

This is informational only: The VMs are normally already pre-configured according to your expected email load. However if you expect that your load is different from the ordered VM, adjust the performance configuration according to VM Resource Configuration.

Optional settings

Add host mapping for XCC

This is only required if the MTAs cannot resolve the domain of the XCC via DNS:

SSH connect to each MTA
Edit /etc/hosts, e.g. sudo nano /etc/hosts
Add a line with the IP and domain of the XCC:
hosts
1.2.3.4 xcc.example.com

Change Docker IP range

This is only required if your local network uses the 172.16.0.0/12 IP address range. As xorlab uses the same IP range internally, this can lead to routing problems. Follow these instructions to change the xorlab internal Docker network. This must be done for every xorlab VM (MTA and XCC).

To verify that xorlab actually uses 172.16.0.0/12 internally, you can execute ip r on the command line. The output usually looks like this:

ip r
...
172.17.0.0/16 dev docker0 proto kernel scope link src 172.17.0.1 linkdown
172.18.0.0/16 dev br-74362b0b174e proto kernel scope link src 172.18.0.1
...

Open the daemon.json file:
daemon.json
sudo vi /etc/docker/daemon.json
Specify the new IP range that xorlab should use internally. You have to set a subnet for bip and a different one for default-address-pools. Make sure you don’t use those subnets in your network. More information can be found on the official Docker documentation: Networking overview and dockerd.
{ ... "bip": "10.200.0.1/24", "default-address-pools":[ {"base":"10.201.0.0/16","size":24} ] }
To activate the changes, stop all running containers by executing docker compose down in the following directories:
- MTA: /etc/xorlab/activeguard, and /etc/xorlab/monitored_mta
- XCC: /etc/xorlab/xcc, /etc/xorlab/auth, /etc/xorlab/elastic, and /etc/xorlab/monitoring
Restart the Docker service with:
service docker restart
Recreate the existing networks by executing docker network rm <network> && docker network create <network> for the following <network>:
- MTA: activeguard.xor and monitored_mta.xor. You can display existing networks with docker network ls.
- XCC: xcc.xor, auth.xor, and monitoring.xor
Restart the VM:
sudo reboot

Replace built-in certificates

This is only applicable if you want to replace the pre-installed dummy certificates. These certificates allow for encryption of traffic but not for authentication. To install new TLS certificates, you have to:

Replace the dummy certificate files on both the XCC and MTAs in /etc/xorlab/tls with your certificate files in PEM format:

If certificates are used that are not signed by a generally trusted CA, i.e. self-issued / locally trusted certificates, you need to configure XCC and MTA VMs to trust all certificates:

/etc/xorlab/<stack>/bootstrap.env (auth, monitoring and xcc stacks)

## xorlab bootstrap configuration
(...)
# 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}}}

/activeguard/core/active_guard.yml (using Expert Editor)

serviceProviders:
(...)
  xcc:
    hosts:
      - https://xcc.example.com:9080
    ssl:
      trustAll: true

/monitored_mta/promtail/config.yml (using Expert Editor)

clients:
  - url: https://xcc.example.com:3100/loki/api/v1/push
    tls_config:
      insecure_skip_verify: true

/activeguard/mta/audit/audit.yml (using Expert Editor)

serviceProviders:
(...)
  xcc:
    hosts:
      - https://xcc.example.com:9080
    ssl:
      trustAll: true

/etc/xorlab/<stack>/bootstrap.env (activeguard, monitored_mta, rproxy_mta stacks)

## xorlab bootstrap configuration
(...)
# If an untrusted certificate is used on xcc, set 'trustAll' to 'True'
configServiceProvider_ag_local={'serviceProvider': {'hosts': ['https://xcc.example.com:9080'], 'ssl': {'trustAll': True}}}

Click Publish for the files edited in Expert Editor, then restart all containers on the XCC and MTAs to activate the changes. The active_guard.yml, audit, Promtail, and Grafana settings listed above include entries that require component restarts; see How to Activate the Configuration.

Activate the firewall

This is only applicable if you want to manage a host firewall on the xorlab hosts. By default, new MTA and XCC VMs have their firewalls disabled, although the necessary iptables config files are present. To enable the firewalls, for XCC and each MTA VM, execute the following command:

sudo systemctl enable --now /etc/xorlab/firewall/iptables.service

Post-installation checks

Log in to the xorlab MTA admin interface on port 8443.
Go to Health Check and confirm that the status is RUNNING.
Go to Configuration → System Tests and confirm that all System Tests are green.

Further steps

When the VM setup is finished, proceed to configuring monitoring tools.
Start integrating xorlab into your environment: On-prem Integration.

​Preparation

​Hardware requirements

​Network requirements

​Register required DNS records

​Prepare the VMs

​Setup

​Configure the network

​Connect via SSH

​Resize the disk

​Run the Setup Script

​EHLO configuration

​Set local NTP servers

​Configure performance resources

​Optional settings

​Add host mapping for XCC

​Change Docker IP range

​Replace built-in certificates

​Activate the firewall

​Post-installation checks

​Further steps

Preparation

Hardware requirements

Network requirements

Register required DNS records

Prepare the VMs

Setup

Configure the network

Connect via SSH

Resize the disk

Run the Setup Script

EHLO configuration

Set local NTP servers

Configure performance resources

Optional settings

Add host mapping for XCC

Change Docker IP range

Replace built-in certificates

Activate the firewall

Post-installation checks

Further steps