Skip to content

Software XoT Installation Guide

1. Overview

This guide provides instructions for installing the Software XoT on a compatible Linux system. The Software XoT can function as either an XoT-Lock, protecting specific assets, or an XoT-Bridge, facilitating connections between XoT-Clients and XoT-Locks.

This document covers the necessary prerequisites, network interface configuration using Netplan, detailed steps for both manual and Ansible-based installations, and essential post-installation procedures to ensure the Software XoT is operational and registered with the XMS.

2. Prerequisites

The XoT for Linux can be installed on any amd_64 compatible compute platform. Bare metal, on premise VMware or KVM Virtual Machine or Cloud instance.

Minimum recommendations

Use a physical or virtual machine running:

  • 2x vCPU

  • 2GB RAM

  • 16 GB storage

  • OS: Ubuntu 22.04 or later

  • 2x Ethernet interfaces

  • If you plan to configure the Software XoT as a bridge then one of them can be a dummy adapter, meaning you will just need one actual physical adapter.

Network requirements

  • Network interface #1 supports static or DHCP-based IP assignment. It needs reachability to:

  • XMS over TCP/443

  • XoT-Bridge (if used) over UDP/25008 and UDP/17396 (configurable in XMS)

  • Discovery Service over TCP/443

    • https://discovery.prod.xertififed.net

    • Optional: Discovery service local to XMS if DNS spoofing is performed.

  • Network interface #2 is configured from the XMS and depends on the use case.

Xertified Package Repository Access

The Xertified Apt Package Repository uses client certificate authentication. This means you need to acquire some credentials to be able to access the repository. To acquire these credentials, you can use the package repository setup script with your access key:

wget https://share.xertified.net/install/xertified_apr_setup.sh
chmod +x xertified_apr_setup.sh
sudo ./xertified_apr_setup.sh

When running the script like this you will be prompted for your access key, simply enter it and press enter. If you have not been given an Xertified APR access key, please contact support to be provided with one.

3. Configuring Network Interfaces

An XoT requires two network interfaces, eth-ext (external) and eth-dev (device-side). While there must be two interfaces with these exact names, their usage differs depending on the role. For an XoT-Lock, both interfaces are actively used and the eth-dev interface will be automatically configured by XMS. In this configuration it should not have IP addresses set by Netplan (or similar).

If the Software XoT is instead configured as an XoT-Bridge, only the eth-ext interface is operationally required for establishing connections. The eth-dev interface must still be defined during setup, but it does not need to be connected to an active network; configuring it as a dummy is sufficient for XoT-Bridge functionality.

3.1 Ethernet config via Netplan

Create the file "/etc/netplan/02-static-ip.yaml" and use the following template:

network:
  ethernets:
    eth-ext:
      match:
        macaddress: <EXTERNAL_INTERFACE_MAC>
      set-name: eth-ext
      dhcp4: true
    eth-dev:
      match:
        macaddress: <INTERNAL_INTERFACE_MAC>
      set-name: eth-dev
      addresses:
        - <INTERNAL_INTERFACE_IP>
      ignore-carrier: true
      dhcp4: false
  version: 2

Remember to change the above with the actual MAC addresses for the network interfaces on the system.

For example:

network:
  ethernets:
    eth-ext:
      match:
        macaddress: 00:be:43:95:3e:9e
      set-name: eth-ext
      dhcp4: true
    eth-dev:
      match:
        macaddress: 9c:a2:f4:ca:38:1d
      set-name: eth-dev
      addresses:
        - 169.254.49.49/32
      ignore-carrier: true
      dhcp4: false
  version: 2

If unsure of your config is correct, use:

sudo netplan try

If the revert fails, then reboot your system to complete the revert process.

When you are happy with your configuration, press "Enter" to accept the new configuration, or run:

sudo netplan apply

To make the netplan configuration persist between reboots, the following command should be executed:

echo 'network: {config: disabled}' | sudo tee /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg

4. Manual Installation

4.1 Disclaimer

This guide covers only the Software XoT installation, it does not specify how to properly set up and harden your system. Please follow best practices in addition to the steps in this manual guide. Make sure to configure your ssh service with user accounts good passwords, restrict SSH access to root users etc.

If you would like more assistance in setting up your system you can use the Ansible installation instead (see section 5) as this will configure SSH, logrotate etc.

4.1 Install WireGuard Tools

sudo apt-get install wireguard-tools

4.2 Add Xertified Deb Package Repository

In order to further protect the binaries, an extra layer of protection exists in the form of a requirement for a client certificate. The client certificate and corresponding key can be downloaded directly from Xertified Docs Repo but note that the archive is password protected.

For example:

curl -u "user:password" -sLO https://docs.xertified.com/repo_client_certificates.tar.gz.gpg
gpg --decrypt repo_client_certificates.tar.gz.gpg > repo_client_certificates.tar.gz
tar xf repo_client_certificates.tar.gz

The two certificates should be placed in the '/etc/apt' directory and set to be owned by user '_apt' and group 'root', e.g:

chown _apt:root /etc/apt/client*

Permissions need to be set as follows:

  • client_internal_key.pem: read and write only by user (0600 in octal)
  • client_internal_cert.pem: world-readable but only user-writeable (0644 in octal)

For example:

sudo mv ./client_internal* /etc/apt/
sudo chown _apt:root /etc/apt/client*
sudo chmod 0600 /etc/apt/client_internal_key.pem
sudo chmod 0644 /etc/apt/client_internal_cert.pem

An extra configuration file should also be created for apt in /etc/apt/apt.conf.d/99xertified with the following contents:

Acquire::https::pkg.common.xertified.net {
    SslCert "/etc/apt/client_internal_cert.pem";
    SslKey "/etc/apt/client_internal_key.pem";
}

Fetch now the required GPG keys with the help of the previously downloaded certificates:

curl -fsSL --cert /etc/apt/client_internal_cert.pem \
--key /etc/apt/client_internal_key.pem \
https://pkg.common.xertified.net/keys/xertified-release.asc | sudo gpg --dearmor -o /usr/share/keyrings/xertified-release.gpg

echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/xertified-release.gpg] https://pkg.common.xertified.net/ubuntu jammy v3 generic' | sudo tee /etc/apt/sources.list.d/xertified.list

sudo apt-get update

4.3 Install required libraries

sudo apt-get install libnl-3-200 libnl-genl-3-200 libnl-route-3-200 xotd-pkcs11

4.4 Install xotd service

sudo apt-get install xotd

5. Ansible Installation

In addition to the server requirements above, you will need to have Python installed on your target server for Ansible Managed Node support, and an administrator PC with support Ansible Control Node support.

You will also need the Xertified Ansible Deployment Scripts and SSH access to the target server.

5.1 Server Setup

5.1.1 User setup

The Ansible requirements on the managed node are relatively minimal: It requires SSH access, sudo for running tasks that require elevated privileges, as well as Python.

Since modern versions of Ubuntu come with python3 preinstalled, you should not have to install this manually. You will, however, need to have a user on the server through which Ansible can connect with SSH and use sudo.

5.1.2 Setup SSH

sudo apt-get update
sudo apt-get install openssh-server
sudo ufw allow ssh
sudo systemctl enable ssh

5.1.3 Restart the SSH server

sudo systemctl restart sshd

5.2 Control Node Setup

5.2.1 Ansible Control Node Support

sudo apt-get update
sudo apt-get install python3 python3-pip
python3 -m pip install --user ansible
ansible --version

If your system cannot find Ansible, then make sure the installed binaries are in your PATH. If your installation is in ~/.local/bin then that may not be in your path until your environment is reloaded. .profile will sometimes only include this folder in PATH if the directory exists when .profile is run.

5.2.2 Configure Ansible

Create an Ansible hosts file (~/ansible-hosts) and set the server IP of the Ansible Managed Node(s).

[vxot]
<ANSIBLE_MANAGED_HOST_IP> [ansible_user=<MANAGED_NODE_USER>]

Set \ to an IP that you can access the target machine at. It will probably be the IP that the eth-ext interfaces have gotten (after "1.3 Ethernet config via Netplan")

If the user on the managed host is different from the user you are currently running as, you can specify what user to connect to with ansible_user. You can skip this step and instead pass -u when running the playbook.

Example:

[vxot]
192.168.1.53 ansible_user=vxotadmin

Configure Ansible to use your custom Ansible hosts file. If installing Ansible from a package manager, the latest ansible.cfg file should be present in /etc/ansible where you add/edit the following line.

inventory = ~/ansible-hosts

5.2.3 Create and upload SSH key to server

For the playbook to be able to run against the managed node, the user running Ansible needs to have access to the managed node system. The public SSH key of the user running Ansible on the control node will need to be added to ~/.ssh/authorized_keys on the target system for the intended remote user.

To configure SSH key access, you can do the following:

ssh-keygen -t ed25519 -C "<YOUR_EMAIL>" -f ~/.ssh/id_ansible
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ansible
ssh-copy-id -i ~/.ssh/id_ansible.pub <MANAGED_NODE_USER>@<MANAGED_NODE_IP>

Remember to replace any above with the actual values for your installation.

5.3 Software XoT Server Installation

5.3.1 Download and run the Ansible playbook

Receive the Ansible playbook from Xertified. It is usually git-cloned from a Bitbucket repository (e.g., git clone https://username@bitbucket.org/xertified/deployment.git; Authentication is required) But it can also be distributed as a zip file.

It is possible to run the playbook with the --check flag specified to verify the playbook. This may lead to some errors that would not occur when running the playbook. If, for instance, running with the check flag causes errors when trying to download and install packages, this may be a false positive.

ansible-playbook --ask-become-pass playbook_v3_xotn_ubuntu.yml

The --ask-become-pass flag (or -K for short) will let you enter the sudo password when running the playbook.

6. Post Installation

6.1 Starting XoT

After the installation process, manual or automated, the xotd daemon needs to be started:

sudo systemctl start xotd.service

Depending on where the software XoT is installed, on a cloud hosting service (AWS, Azure, etc.) or a virtual machine through on-premise virtualization platforms (e.g., VMware, Proxmox, etc.), firewall solutions that control UDP traffic should be examined.

6.2 Registering on XMS server

Provided that the MAC address of the eth-ext network adapter is in the discovery service database and points to the correct XMS server, a registration URL will appear in the logs of the xotd. An easy way to find is with the following command:

grep URL /xotd/tmp/*-log.txt

Paste the link into a web browser, log in to the XMS interface, and proceed to further configure it.