Skip to content

Software XoT Installation Guide (Legacy)

Version Note: This guide is for OVA versions before XoT-Appliance-v3.7.2-2. For newer versions, see XoT.md.

1. Overview

This guide provides instructions for deploying the 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

  • Network interface #1 (eth-ext) 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.xertified.net
    • Optional: Discovery service local to XMS if DNS spoofing is performed

  • Network interface #2 (eth-dev) is configured by the xotd service based on XMS configuration, it is not needed for XoT-Bridges:

  • For XoT-Lock: Both interfaces are actively used; eth-dev will be automatically configured by XMS

  • For XoT-Bridge: Only eth-ext is operationally required

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. During deployment:

  • Ensure at least 16 GB of storage is allocated
  • Map two network adapters:
  • Network adapter 1: Connect to the network that provides external connectivity (will become eth-ext)
  • Network adapter 2: Connect to the device-side network or a dummy network (will become eth-dev)

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. List available interfaces: Shows all network interfaces with their MAC addresses
  2. Select external interface: Choose which interface should be eth-ext (external side)
  3. Choose deployment mode:
  4. Standard XoT-Lock mode: Requires selecting a second interface for eth-dev
  5. XoT-Bridge mode: Only eth-ext is configured; eth-dev is omitted

The script will:

  • Validate your selections
  • Create the netplan configuration at /etc/netplan/02-xot-interfaces.yaml
  • Apply the configuration immediately (no reboot required)
  • Disable cloud-init network management to persist settings
  • Start the xotd service
  • Wait for xotd to initialize successfully before enabling it for boot

Safety Feature: If xotd fails to start (e.g., due to network misconfiguration), the service will not be enabled for automatic startup, preventing boot loops.

6.2 Verify Network Configuration

After the script completes, verify the interfaces:

ip addr show eth-ext
ip addr show eth-dev  # Only if configured in standard mode

You should see eth-ext with an IP address from DHCP and eth-dev (if configured) with the expected configuration.

6.3 Reconfiguring Network Interfaces

If you need to change the network configuration later, simply run xot-setup again. The script will detect the existing configuration and allow you to reconfigure.

6.4 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)
  • For XoT-Lock deployments, an interface named eth-dev must also exist (device/protected interface)

7. Configuring Package Updates

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

Note: Depending on your OVA version, this script may be named xertified_apr_setup or xot-repo-setup.

7.1 Run xertified_apr_setup

sudo xertified_apr_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:

sudo apt update
sudo apt upgrade

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 allow 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

After xotd restarts, it will contact the Discovery Service and obtain an enrollment URL.

9.1 Get the Enrollment URL

Use the xotd-enrollment-url helper script:

xotd-enrollment-url

Note: Depending on your OVA version, this script may be named xotd-enrollment-url or xot-enrollment-url.

This will extract and display the enrollment URL from the xotd logs.

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 Complete Enrollment

  1. Copy the enrollment URL from the output
  2. Paste the link into a web browser
  3. Log in to the XMS interface
  4. Complete the enrollment process

For detailed enrollment instructions, see the Enrolling XoTs guide.

9.3 Next Steps

After enrollment, configure the XoT from the XMS:

10. Additional Administrative Tools

10.1 Factory Reset

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

sudo xotd-factory-reset

Note: Depending on your OVA version, this script may be named xotd-factory-reset or 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.2 Service Management

Check xotd service status:

sudo systemctl status xotd

View xotd logs:

sudo journalctl -u xotd -f

Or view the xotd log files directly:

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

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 and ip route
  4. Run xot-setup again to reconfigure if needed

11.3 Enrollment URL Not Appearing

If xotd-enrollment-url reports no URL found:

  1. Verify xotd is running: sudo systemctl status xotd
  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

11.4 Cannot SSH to the VM

If you cannot connect via SSH:

  1. Verify network connectivity from the hypervisor console
  2. Ensure the SSH service is running: sudo systemctl status ssh
  3. Check firewall rules if applicable
  4. Verify you're using the correct credentials (see https://support.xertified.net)

12. Security Setup

  1. Change default password immediately upon first login
  2. Add SSH keys for secure access
  3. Delete the password authentication override after adding SSH keys: 
    sudo rm /etc/ssh/sshd_config.d/99-ova-default-password.conf
sudo systemctl restart ssh
  4. Keep software updated using apt update && apt upgrade
  5. Enable automatic security updates if desired (optional)
  6. 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-setup Configure network interfaces (eth-ext/eth-dev) sudo xot-setup
xertified_apr_setup Configure APR repository access for updates sudo xertified_apr_setup
xotd-enrollment-url Display enrollment URL from logs xotd-enrollment-url
xotd-factory-reset Reset to factory defaults sudo xotd-factory-reset

14. Support

For additional assistance, please contact: