Linux Images

Last updated: May 31, 2026Latest Frontend Version: 2.16.20

Supported Distributions

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

Manual Image Creation

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

1. Confirm OpenSSH is installed but its service is disabled (step 4).
2. 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.

7. Install Applications (Optional)

Install any software, desktop environments, development tools, or organizational policies required. 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.

8. Finalize

1. Shut down the VM.
2. 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.

---

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:

1. Copying the base cloud image to the output path.
2. Using virt-customize to mount the image and execute each snippet in sequence inside the guest filesystem.
3. Injecting the VM Installer package and the specified controller.toml.
4. 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:

1. Create a new .sh file in the snippets/ directory.
2. 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.

---

Debugging

If the image fails to register after deployment, access the VM directly via VNC to diagnose.

Prerequisites

Before booting the VM for debugging:

1. In the tiCrypt frontend, set the video attribute to VNC on the hardware setup. This places the VM in debug mode.
2. Set registration-timeout-debug to at least 1 hour.

All commands below require root access on the VM host.

VNC Access

List running VMs and find yours (typically the last entry):

virsh list

Get the VNC display port:

virsh vncdisplay vm-<uuid>

VNC binds to localhost. Forward the port to your desktop via SSH:

ssh -L 5901:localhost:5900 vm-host

Connect your VNC client to localhost:1. If the display port is :10, change the remote port to 5910.

Checklist

Log in as root via VNC and verify:

Check	Command	Expected
Network	nmcli d	eth0 present and connected
Controller service	systemctl status ticrypt-vm-controller.service	Active, no errors
Controller logs	journalctl -u ticrypt-vm-controller.service	No registration, download, or port-binding errors
SSH disabled	systemctl status sshd	Inactive. If active, it is blocking port 22

Modifying an Image In Place

To fix an image directly on the VM host without transferring it:

1. Shut down all VMs using the image.
2. Boot a temporary VM from the image:

virt-install --name fix-image \
  --vcpus 1 --ram 1024 \
  --controller type=scsi,model=virtio-scsi \
  --disk /ticrypt/libvirt/pools/ticrypt-bricks/linux.qcow2,bus=scsi,size=80 \
  --import --graphics vnc --noautoconsole \
  --network bridge=virbr0

3. Connect via VNC (virsh vncdisplay fix-image), apply fixes, then shut down.
4. Clean up: virsh undefine fix-image