Linux Images

Last updated: August 1, 2026Latest Frontend Version: 2.17.4

Supported Distributions

Distribution	Status
RHEL 8+ / Rocky Linux 8+ / AlmaLinux 8+	Recommended
Ubuntu 20.04+ / Debian 11+	Supported

Manual Image Creation

Step Overview

📋Steps at a Glance

1. Create a virtual machine

2. Install the VM Installer

3. Configure networking

4. Disable SSH

5. Configure the controller

6. Configure NFS client

7. Configure XRDP (remote desktop)Optional

8. Enable SFTPOptional

9. Install applicationsOptional

10. Finalize

1. Create a Virtual Machine

Use any hypervisor that produces qcow2 images:

Virtual Machine Manager (free, Linux)
VirtualBox (free, cross-platform)
QEMU/KVM via command line

Attach your distribution's ISO as a CD-ROM and install the OS. Create only a root account.

2. Install the VM Installer

Download the package for your distribution:

RHEL / Rocky / AlmaLinux (RPM): Linux
Ubuntu / Debian (DEB): Ubuntu

If the tiCrypt package repository is configured on the image:

dnf install ticrypt-vm-controller
systemctl enable ticrypt-vm-controller.service

3. Configure Networking

The interface must be named eth0 and use DHCP. Create or replace /etc/sysconfig/network-scripts/ifcfg-eth0:

TYPE=Ethernet
DEVICE=eth0
BOOTPROTO=dhcp
ONBOOT=yes

caution

Hypervisors like VirtualBox assign different interface names (e.g., enp0s3). The tiCrypt infrastructure requires eth0. Networking will fail without this configuration.

4. Disable SSH

The VM Controller binds to port 22 at boot. If OpenSSH holds that port, the controller cannot start and registration fails.

systemctl disable sshd

tip

During image preparation, temporarily change the SSH port in /etc/ssh/sshd_config (e.g., to 2022) to keep remote access. Disable SSH as the final step before shutdown.

5. Configure the Controller

Edit /etc/ticrypt/controller.toml. See Controller Configuration for the full reference.

6. Configure NFS Client

tiCrypt VMs mount NFS shares from tiCrypt storage for file access. The NFS client utilities must be installed and the required services enabled.

Install NFS utilities:

RHEL / Rocky / AlmaLinux
Ubuntu / Debian

dnf install -y nfs-utils

apt-get install -y nfs-common rpcbind

Enable the required services:

The rpcbind service handles RPC program number lookups, and rpc-statd manages NFS file locking. The nfs-client.target groups all NFS client services. These must be explicitly enabled because the VM Controller mounts storage imperatively at boot rather than through /etc/fstab, so systemd's fstab-triggered generators do not pull them in automatically.

systemctl enable --now rpcbind
systemctl enable --now nfs-client.target
systemctl enable --now rpc-statd

SELinux (RHEL / Rocky / AlmaLinux only):

SELinux gates user-process access to NFS-mounted paths with the use_nfs_home_dirs boolean. Despite the name, this controls access to all NFS content, not just home directories. Without it, desktop applications and shell sessions will receive permission denials when accessing NFS-mounted project shares:

setsebool -P use_nfs_home_dirs on

Verify the NFS client is operational:

rpcinfo -p localhost

The output should list portmapper and status (rpc.statd). The nlockmgr entry only appears after an actual NFS mount engages the lock manager, so its absence at this stage is expected. You can test connectivity to the storage server with showmount -e <storage-ip> once the VM is on the network.

note

tiCrypt VMs operate on an isolated VLAN with no Active Directory or NIS. NFS mounts use AUTH_SYS (UID/GID-based) authentication. The VM Controller handles mount operations at boot, so no /etc/fstab entries are needed in the image.

7. Configure Remote Desktop (Optional)

Enable this if users need a graphical desktop session via RDP. The configuration depends on your Rocky/RHEL version.

	Rocky 8/9 + XRDP	Rocky 10+ + GNOME Remote Desktop
Guide	XRDP Configuration	GNOME Remote Desktop
Desktop	Xfce / MATE (lightweight)	GNOME (heavier, ~2 vCPU / 2 GB RAM minimum)
Authentication	Single login prompt	Single login (headless mode, provisioned via `controller.toml` hook)
Clipboard control	Full directional control	Not available
Multi-user	Built-in terminal-server multiplexing	Native multi-user via GDM session routing
Session reaping	Built-in	Manual (`loginctl`)
Best for	Secure-research VMs needing clipboard restriction	General-purpose VMs, or when Rocky 10 is required

8. Enable SFTP (Optional)

SFTP allows users to transfer files from their local machine into the VM while running tiCrypt. The connection is one-way only: uploads are permitted, downloads and file reads are not.

Confirm OpenSSH is installed but its service is disabled (step 4).
Set sftpEnabled = true in the [tunnel] section of controller.toml.

The VM Controller runs its own SSH daemon restricted to SFTP uploads, with no console access or file reads. See the SFTP parameters in the configuration reference.

9. Install Applications (Optional)

Install any required software, desktop environments, or development tools, and apply any required organizational policies. tiCrypt imposes no restrictions on installed software.

If any installed software requires license activation or periodic license checks (e.g., SAS, ArcGIS, Adobe), the licensing server must be added to the Licensing Servers allowlist in the tiCrypt frontend before the VM can reach it.

10. Finalize

Shut down the VM.
Verify the image is in qcow2 format. Convert if necessary:

qemu-img convert -f raw -O qcow2 input.img output.qcow2

The image is ready to be added to tiCrypt. If you encounter registration issues after deploying the image, see the Troubleshooting guide.

Automated: Linux Image Builder

tiCrypt provides an image builder that automates Linux VM image creation. It uses a YAML configuration file and a modular snippets system to produce deployment-ready qcow2 images.

Prerequisites

Requirement	Details
Host OS	Linux with root access
libguestfs-tools	Provides `virt-customize`, used to mount and modify the image. Install via `dnf install libguestfs-tools` or `apt install libguestfs-tools`
Base cloud image	A generic cloud image in qcow2 format (e.g., `Rocky-8-GenericCloud.latest.x86_64.qcow2`)
Builder package	The `ticrypt-image-builder` tarball from your tiCrypt administrator

Package Contents

Path	Description
`ticrypt-image.sh`	Main build script
`docs/`	Build documentation and example YAML configurations
`snippets/base.sh`	Base system: configures `eth0` networking, installs the VM Installer RPM, enables the controller service, disables `sshd`, installs core packages
`snippets/post.sh`	Image sealing: removes SSH host keys, clears logs and temporary files, trims the filesystem
`snippets/xrdp.sh`	XRDP remote desktop environment
`snippets/xrdp/*.sh`	Per-application scripts: Chrome, Docker, JupyterLab, RStudio, Python, PostgreSQL, etc.
`snippets/terminal.sh`	Terminal-only image (no desktop environment)
`snippets/slurmController.sh`	Slurm controller node
`snippets/slurmWorker.sh`	Slurm worker node
`configs/*.toml`	Pre-built `controller.toml` files for common image types

Build Process

The builder works by:

Copying the base cloud image to the output path.
Using virt-customize to mount the image and execute each snippet in sequence inside the guest filesystem.
Injecting the VM Installer package and the specified controller.toml.
Running the post.sh snippet to seal the image.

Invocation

sudo ./ticrypt-image.sh config.yaml

Root is required because virt-customize needs access to the guest filesystem.

YAML Configuration

The builder reads a YAML file that specifies the base image, output path, controller configuration, and snippet sequence:

base_image: "Rocky-8-GenericCloud.latest.x86_64.qcow2"
output_image: "rocky8-xrdp.qcow2"
controller_config: "configs/xrdp.toml"
snippets:
  - base.sh
  - xrdp.sh
  - xrdp/chrome.sh
  - xrdp/rstudio.sh
  - xrdp/python.sh
  - post.sh

caution

base.sh must be the first snippet (it sets up networking, packages, and the VM Installer). post.sh must be the last (it seals the image by removing host keys and temporary files).

Writing Custom Snippets

Snippets are shell scripts executed inside the guest filesystem via virt-customize --run. They run as root in the guest context. To add custom software or configuration:

Create a new .sh file in the snippets/ directory.
Reference it in your YAML configuration between base.sh and post.sh.

Example custom snippet (snippets/custom-app.sh):

#!/bin/bash
dnf install -y my-custom-package
systemctl enable my-custom-service
cp /tmp/my-config.conf /etc/my-app/config.conf

Pre-built Controller Configurations

The configs/ directory includes ready-to-use TOML files:

File	Use Case
`xrdp.toml`	Desktop images with XRDP remote access
`terminal.toml`	Terminal-only images (no GUI)
`slurmController.toml`	Slurm controller nodes
`slurmWorker.toml`	Slurm worker nodes

See Controller Configuration for parameter details.

Supported Distributions​

Manual Image Creation​

Step Overview​

1. Create a Virtual Machine​

2. Install the VM Installer​

3. Configure Networking​

4. Disable SSH​

5. Configure the Controller​

6. Configure NFS Client​

7. Configure Remote Desktop (Optional)​

8. Enable SFTP (Optional)​

9. Install Applications (Optional)​

10. Finalize​

Automated: Linux Image Builder​

Prerequisites​

Package Contents​

Build Process​

Invocation​

YAML Configuration​

Writing Custom Snippets​

Pre-built Controller Configurations​

Supported Distributions

Manual Image Creation

Step Overview

1. Create a Virtual Machine

2. Install the VM Installer

3. Configure Networking

4. Disable SSH

5. Configure the Controller

6. Configure NFS Client

7. Configure Remote Desktop (Optional)

8. Enable SFTP (Optional)

9. Install Applications (Optional)

10. Finalize

Automated: Linux Image Builder

Prerequisites

Package Contents

Build Process

Invocation

YAML Configuration

Writing Custom Snippets

Pre-built Controller Configurations