VM Images Overview

Last updated: June 1, 2026Latest Frontend Version: 2.16.20

A VM image is the boot drive of every virtual machine in tiCrypt. It contains the operating system, a tiCrypt VM Installer, a controller.toml configuration, and any pre-installed applications or policies your organization requires.

tiCrypt does not restrict what goes into an image. Install any OS, applications, GPOs, or tooling your users need. The only tiCrypt-specific components are the VM Installer and its configuration file.

Architecture

The VM system consists of three layers that work together at boot:

Layer	Component	Role
Image	VM Installer	Bootstrap software baked into the image. First tiCrypt process to run at boot. Downloads the latest controller binary, generates keys, and supervises the controller lifecycle
Image	controller.toml	Per-image configuration file. Defines terminal access, tunneling, SFTP, lifecycle commands, user management, and all other controller behaviors
Runtime	VM Controller	Downloaded at boot by the VM Installer. Enforces security policy, registers with the backend, creates user accounts, mounts encrypted drives, and proxies all user traffic
Infrastructure	Controller Server	Backend service that distributes the global configuration and the latest VM Controller binary to every VM at boot

The VM Installer and controller.toml are the only components you install on the image. The VM Controller itself is always fetched fresh from the Controller Server, ensuring every VM runs the latest version without rebuilding images.

Security Model

tiCrypt VMs operate in a fully locked-down network environment:

• No open ports. The tiCrypt network infrastructure blocks all inbound and outbound traffic except port 22, which the VM Controller binds to at startup.
• Mutual authentication. The VM Controller generates an RSA-2048 key pair at each boot. The backend and the VM owner authenticate each other via public key exchange before any user data enters the VM.
• Encrypted drives. User data is stored on encrypted drives mounted at runtime using LUKS (Linux) or BitLocker (Windows). Drive keys are transmitted over the authenticated channel and never persist on the boot image.
• No SSH access. SSH daemons must be disabled on the image. All user interaction flows through the VM Controller's terminal and tunneling services, which are proxied through the tiCrypt backend and fully audited.
• Registration timeout. VMs that fail to register within the configured timeout (typically 5 minutes) are automatically terminated by the backend. This prevents unregistered or compromised VMs from persisting in the environment.

Licensing and External Server Access

VMs run in a locked-down network with no outbound access by default. Software that requires activation or periodic license checks (e.g., Windows activation, SAS, ArcGIS, Adobe) cannot reach external servers unless explicitly permitted.

To allow VMs to communicate with licensing or activation servers, administrators configure a Licensing Servers allowlist under Management in the tiCrypt frontend. Each entry specifies a domain or server that all VMs in the realm are permitted to contact. This applies to both Linux and Windows images.

tip

Configure the licensing allowlist before deploying images that depend on external activation. Without it, the software will fail to activate inside the VM. See Licensing Servers in the Admin Guide for setup instructions.

Boot and Registration Sequence

1. The tiCrypt backend starts the VM and assigns a UUID.

2. The VM boots from the image and starts the VM Installer service.

3. The VM Installer contacts the Controller Server and downloads the latest global configuration and VM Controller binary.

4. The VM Controller initializes:

   • Generates an RSA-2048 key pair.
   • Binds to port 22. If the port is occupied (e.g., by sshd), registration aborts.
   • Sends its UUID and public key to the backend. The backend responds with configuration data and the owner's public key.
   • Opens a WebSocket to the backend, awaiting the owner's frontend session.

5. If registration does not complete within the timeout, the backend terminates the VM.

6. When the owner connects through the tiCrypt frontend, mutual authentication occurs. After authentication:

   • Encrypted drives are attached and mounted (LUKS or BitLocker).
   • The user database on the first drive provisions accounts, groups, and directories.
   • Terminal, tunneling, and SFTP services become available per the controller.toml configuration.

Common Integration Failures

Cause	Explanation
VM Installer does not start	Service not installed, not enabled, or lacks root/Administrator privileges
Controller download fails	VM cannot reach the Controller Server on the internal network
Port 22 occupied	An SSH daemon or other service holds the port. Disable it before finalizing the image
Backend unreachable	VM Controller cannot reach the backend to register or open the WebSocket

Image Requirements

Every VM image must include:

Component	Location	Purpose
tiCrypt VM Installer	RPM/DEB (Linux) or MSI (Windows)	Bootstrap and supervise the VM Controller
controller.toml	/etc/ticrypt/controller.toml (Linux) or C:\Program Files\Tera Insights\tiCrypt VM Controller\controller.toml (Windows)	Define controller behavior for this image

Beyond these, add any software or configuration your users need. See the Linux and Windows image creation guides for step-by-step instructions.

Supported Approaches

Approach	Linux	Windows
Manual	Install the OS, VM Installer, and configure networking	Install Windows, VirtIO drivers, and the VM Installer
Automated	tiCrypt Image Builder	Ansible playbook

Both approaches produce a qcow2 disk image, the format tiCrypt accepts.