Skip to content

Software XoT Installation Guide

Version Note: This guide is for XoT-Appliance-v3.7.2-2 or later. For earlier OVA versions, see XoT-legacy.md.

1. Overview

This guide provides instructions for deploying the latest XoT Appliance. This version includes automated setup scripts that simplify the configuration process compared to older releases.

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.

2. Prerequisites

2.1 System Requirements

The Software XoT VM is configured with the following specifications:

  • 2x vCPU
  • 2GB RAM
  • 16 GB storage
  • OS: Ubuntu 22.04 LTS (pre-installed)
  • 2x Ethernet interfaces

2.2 Hypervisor Support

The Software XoT is distributed as an OVF with VMDK disk image, which is natively supported by several virtualization platforms including VMware ESXi/vSphere, VMware Workstation/Fusion, VirtualBox, and others.

For platforms that don't support OVF directly, the VMDK can be converted to other formats (QCOW2, VHD, etc.) using standard tools.

Note: Contact Xertified Support if you need assistance with deployment on your platform.

2.3 Network Requirements

Two network interfaces are strongly recommended for all deployments. This allows the XoT to function as either an XoT-Lock or XoT-Bridge without reconfiguration.

Warning: If you deploy with only one network interface (bridge-only mode), the XoT cannot protect assets. Adding an asset to a bridge-only XoT will fail because the required eth-dev interface is not present. If there is any possibility you may need to protect assets in the future, deploy with two interfaces.

Outbound connectivity from the external interface to:

  • XMS over TCP/443
  • Discovery Service (https://discovery.prod.xertified.net) over TCP/443 (unless using local discovery)
  • XoT-Bridge (if used) over UDP/25008 and UDP/17396

3. Downloading the VM Image

  1. Log in to your Xertified account at https://support.xertified.com
  2. Select the appropriate software version
  3. Download the XoT Lock/Bridge package

The appliance is available as an OVA file (for VMware and VirtualBox) or QCOW2 (for QEMU/KVM). Some downloads may be provided as a password-protected ZIP file; if so, the ZIP password is noted on the download page.

Default VM login credentials are provided on the download page.

If you do not have access to the support portal, please contact support@xertified.com.

4. Deploying the VM

Import the OVA using your hypervisor's standard OVF/OVA deployment procedure. For QEMU/KVM, use the QCOW2 image directly. Ensure at least 16 GB of storage is allocated and attach one or two network adapters as needed. After deployment completes, power on the VM.

5. Initial Access

After the VM boots, you can access it via the console or SSH.

The default credentials are provided on the download page at https://support.xertified.net.

To connect via SSH:

ssh xot@<ip-address>

Security Note: Change the default password immediately upon first login. After adding your SSH keys, delete the temporary password authentication override file:

sudo rm /etc/ssh/sshd_config.d/99-ova-default-password.conf
sudo systemctl restart ssh

6. Network Configuration with xot-setup

The VM includes the xot-setup script that automates network interface configuration. This script replaces the manual netplan configuration process used in older versions.

6.1 Run xot-setup

sudo xot-setup

The script will guide you through the configuration process:

  1. Select external interface: Choose which interface should be eth-ext (external side)
  2. Configure IP addressing: Choose DHCP or static IP for eth-ext
  3. Select device interface: Choose which interface should be eth-dev, or skip for bridge mode
  4. Configure NTP: Use system defaults or specify custom NTP servers

The script will:

  • Validate your selections
  • Create the netplan configuration at /etc/netplan/90-xot-interfaces.yaml
  • Configure custom NTP servers if specified
  • Apply the configuration immediately (no reboot required)
  • Start the xotd service
  • Wait for xotd to initialize successfully before enabling it for boot

When eth-ext uses DHCP, the XoT reports its XoT ID as the DHCP hostname. It also applies interface MTU from DHCP option 26 and any additional routes delivered through DHCP options 33 and 121.

6.3 Manual Interface Configuration

If you cannot use xot-setup or netplan, you can configure the interfaces manually using any method available on your system. The only requirement is that:

  • An interface named eth-ext must exist (external side interface)
  • It is highly recommended, and required for XoT-Lock deployments, to have an additional interface named eth-dev (device/protected interface)

7. Configuring Package Updates

The VM includes the xot-repo-setup script to configure access to Xertified's APR (Apt Package Repository) for receiving software updates.

Important: Run xot-repo-setup before xot-setup. Once xotd is running, firewall rules will block outbound connections required for repository configuration. If you want to enable updates after xot-setup you need to stop xotd service and temporarily change iptables configuration.

7.1 Run xot-repo-setup

sudo xot-repo-setup

When prompted, enter your Xertified APR Account Key. The script will:

  • Authenticate with the Xertified APR API
  • Download and install the necessary certificates
  • Configure APT sources for the Xertified repository
  • Install the repository GPG key

7.2 Install Updates

After configuring APR access, you can install updates for the xotd service:

sudo apt update
sudo apt install xotd

8. Discovery Service Registration

Before an XoT can be enrolled, its eth-ext MAC address must either be registered in the public Discovery Service, or DNS must point the XoT directly to the your XMS installation. This allows the XoT to locate its XMS server.

8.1 Public Discovery Service

For regular deployments using the public Discovery Service at discovery.prod.xertified.net:

  1. Note the MAC address of your eth-ext interface (shown during xot-setup or via ip link show)
  2. Send the MAC address to support@xertified.com along with your XMS server address (via which the XoT can reach the XMS)
  3. Wait for confirmation that the MAC address has been registered

8.2 Local Discovery (Air-Gapped Environments)

For air-gapped deployments or environments that cannot reach the public Discovery Service, you can use local discovery by overriding DNS:

  1. Configure your local DNS to resolve discovery.prod.xertified.net to your XMS server's IP address
  2. The XMS includes a built-in discovery service that will respond to XoT discovery requests
  3. No MAC address registration with Xertified is required in this configuration

8.3 Restart xotd After Discovery is Configured

Once discovery is configured (either MAC registered or DNS override in place), restart xotd to initiate the discovery process:

sudo systemctl restart xotd

9. XMS Enrollment

Once Discovery has been configured for the XoTs eth-ext MAC-address the xotd service can contact the Discovery Service obtain its XMS URL. When the XoT has successfully contacted XMS, then enrollment can begin.

9.1 Enrollment via URL

To get the enrollment url directly, use the xot-enrollment-url helper script:

xot-enrollment-url

This will extract and display the enrollment URL.

Note: If you receive an error that no enrollment URL is found, the XoT may already be enrolled or xotd may still be initializing. Wait a minute and try again.

9.2 Enrollment via Web Browser

If you are using a console without copy and paste functionality, then it may be easier to start the enrollment webserver which provides a navigable web page which includes both direct-link and QR code for enrollment:

sudo xot-enrollment-webserver

This starts a temporary web server on port 8080. Open the displayed URL in your browser to see a QR code that can be scanned with a mobile device, or click the enrollment link directly.

The webserver automatically exits when enrollment completes or after 3 minutes.

9.3 Complete Enrollment

  1. Scan the QR code or click the enrollment link
  2. Log in to the XMS interface
  3. Complete the enrollment process

For detailed enrollment instructions, see the Enrolling XoTs guide.

9.4 Next Steps

After enrollment, configure the XoT from the XMS:

10. Additional Administrative Tools

10.1 System Status

Check the current system status with:

xot-status

This displays network configuration, xotd service status, current state, and any detected problems with helpful troubleshooting hints.

10.2 Factory Reset

If you need to reset the XoT to factory defaults (clearing all enrollment data), use the xot-factory-reset script:

sudo xot-factory-reset

The script will:

  • Prompt for confirmation (requires typing "RESET" in capitals)
  • Stop the xotd service
  • Clear all enrollment data and configuration
  • Clear temporary files
  • Restart xotd in a clean state

Warning: This permanently deletes all enrollment data and configuration. The XoT will need to be re-enrolled with XMS after a factory reset.

10.3 Service Management

Check xotd service status:

sudo systemctl status xotd

View xotd logs:

sudo journalctl -u xotd -f

Or view/follow the xotd log files directly:

less /xotd/tmp/*-log.txt

tail -f /xotd/tmp/*-log.txt

If eth-ext uses DHCP, these logs now include more detailed DHCP packet information, which is often the fastest way to diagnose lease, routing, or option-handling problems.

11. Troubleshooting

11.1 Network Connectivity Issues

If the XoT cannot reach the Discovery Service:

  1. Verify eth-ext has a valid IP address: ip addr show eth-ext
  2. Test DNS resolution: nslookup discovery.prod.xertified.net
  3. Test connectivity: curl -v https://discovery.prod.xertified.net
  4. Check firewall rules (outbound TCP/443 must be allowed)

11.2 xotd Service Fails to Start

If xotd fails to start after running xot-setup:

  1. Check service status: sudo systemctl status xotd
  2. View detailed logs: sudo journalctl -u xotd -n 50
  3. Verify network configuration: ip addr, ip link and ip route
  4. Run xot-setup to reconfigure if needed

11.3 Enrollment URL Not Appearing

If xot-enrollment-url reports no URL found:

  1. Run xot-status to see current state and any detected problems
  2. Check that eth-ext has network connectivity
  3. Wait a few minutes for xotd to initialize and contact the Discovery Service
  4. Verify the MAC address of eth-ext is registered in the discovery service
  5. Contact Xertified Support to verify your deployment is registered

12. Security Setup

  1. Change default password immediately upon first login
  2. Add SSH keys for secure access
  3. Test SSH key login from another terminal before proceeding
  4. Delete the password authentication override after verifying key login works: 
    sudo rm /etc/ssh/sshd_config.d/99-ova-default-password.conf
sudo systemctl restart ssh
  5. Keep software updated using apt update && apt upgrade
  6. Enable automatic security updates if desired (optional)
  7. Review firewall rules to ensure only necessary ports are accessible

13. Summary of Helper Scripts

The VM includes the following helper scripts for easy administration:

Script Purpose Usage
xot-repo-setup Configure APR repository access for updates sudo xot-repo-setup
xot-setup Configure network interfaces and NTP sudo xot-setup
xot-status Display system and enrollment status xot-status
xot-help Show all commands and support info xot-help
xot-welcome Display welcome message xot-welcome
xot-enrollment-url Display enrollment URL from logs xot-enrollment-url
xot-enrollment-webserver Start enrollment webserver with QR code sudo xot-enrollment-webserver
xot-factory-reset Reset to factory defaults sudo xot-factory-reset

14. Support

For additional assistance, please contact: