Linux Images
Supported Distributions
| Distribution | Status |
|---|---|
| RHEL 8+ / Rocky Linux 8+ / AlmaLinux 8+ | Recommended |
| Ubuntu 20.04+ / Debian 11+ | Supported |
Manual Image Creation
Step Overview
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:
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
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
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 only 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.
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.
| XRDP (Rocky 8/9, or 10 with Xvnc) | Rocky 10+ + GNOME Remote Desktop | |
|---|---|---|
| Guide | XRDP Configuration | GNOME Remote Desktop |
| Desktop | Xfce (8/9) or MATE (10), 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 that need a GNOME desktop |
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 = truein the[tunnel]section ofcontroller.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.
A Linux image is a prepared Linux installation that tiCrypt clones each time a user launches a secure VM. Building one is a one-time task per distribution and version: the operating system, the VM Controller, and any preinstalled software are baked in once, and every VM created from the image starts from that state.
There are two ways to build one. The image builder automates the process from a short configuration file and is the recommended route. The manual process is documented for images the builder does not yet cover.
Automated: Linux Image Builder
tiCrypt provides an image builder that automates Linux VM image creation. You describe the image in a configuration file (image.conf), and the builder customizes a Rocky Linux or AlmaLinux cloud image with a series of snippets to produce a deployment-ready qcow2 image. The download includes a README.md with the full instructions.
Prerequisites
| Requirement | Details |
|---|---|
| Host OS | Linux with root access and KVM |
| libguestfs-tools | Provides virt-customize, used to modify the image. Install via dnf install libguestfs-tools or apt install libguestfs-tools |
| Base cloud image | A Rocky Linux or AlmaLinux GenericCloud image in qcow2 format (e.g., Rocky-9-GenericCloud-LVM.latest.x86_64.qcow2) |
| Internet access | Packages are downloaded during the build. The finished VM does not need internet access |
| Builder package | The ticrypt-image-builder tarball. See Get the Builder below |
Get the Builder
Download and extract the builder on the host where you will run the build:
wget https://storage.googleapis.com/ticrypt/install/ticrypt-image-builder-0.2.0.tgz
tar -xzf ticrypt-image-builder-0.2.0.tgz
This extracts to a versioned directory such as ticrypt-image-builder-0.2.0, containing the build script, snippets, and controller configurations described below.
Package Contents
| Path | Description |
|---|---|
README.md | Full build instructions, including how to install applications |
ticrypt-image.sh | The builder: generate a configuration, then build it |
snippets/base.sh | Base system: EPEL, core packages, the tiCrypt package repository and VM Controller; disables sshd, enables firewalld |
snippets/nfs.sh | NFS client for home directories and research drives |
snippets/terminal.sh, xrdp.sh, slurmController.sh, slurmWorker.sh, clusterController.sh | One snippet per image type |
snippets/xrdp/*.sh | Application add-ons for desktop images: VS Code, Chrome, RStudio, JupyterLab, LibreOffice, Python, PostgreSQL, and more |
snippets/post.sh | Final step: updates all packages and sets the default boot entry |
configs/*.toml | The controller.toml for each image type |
docs/ | The original manual build notes |
Build Process
The builder:
- Copies (or downloads) the base cloud image to the output file.
- Sets the root password and runs an optional setup script.
- Runs
base.sh,nfs.shand the image type's snippet inside the image withvirt-customize, then any application add-ons, extra packages and your own scripts. - Uploads the controller configuration to
/etc/ticrypt/controller.toml. - Runs
post.sh.
The base and final steps always run; you do not list them.
Invocation
./ticrypt-image.sh generate image.conf # write a commented configuration file
nano image.conf # choose the type, base image, applications
sudo ./ticrypt-image.sh build image.conf # build the image
The image is written to <destination_dir>/<name>-<type>-<version>.qcow2. Root is required because virt-customize needs access to the guest filesystem. ./ticrypt-image.sh types lists the image types.
Configuration
image.conf is a bash file. The generated file explains every setting; the main ones are:
base_image_file="Rocky-9-GenericCloud-LVM.latest.x86_64.qcow2" # or base_image_url="https://..."
type="xrdp" # terminal, xrdp, xrdp_slurmController, slurmController, slurmWorker, clusterController
name="ticrypt-image"
version="1.0.0"
destination_dir="."
xrdp_extra_packages=( "vscode" "python" ) # application add-ons (desktop images)
packages=( "git" "htop" ) # extra dnf packages (any image type)
scripts=( "my-tools.sh" ) # your own scripts (any image type)
# config_file="my-controller.toml" # instead of configs/<type>.toml
Writing Custom Snippets
Snippets are shell scripts executed inside the image via virt-customize --run. They run as root, while nothing is running in the image. To add custom software or configuration, either:
- list your script in
scripts=( ... ), or - add it to
snippets/xrdp/(for examplesnippets/xrdp/my-app.sh) and list"my-app"inxrdp_extra_packages.
Example add-on (snippets/xrdp/my-app.sh):
#!/bin/bash
set -euo pipefail
dnf install -y my-custom-package
systemctl enable my-custom-service # enable only; services cannot be started during the build
snippets/xrdp/vscode.sh is a complete example, including how to leave nothing in the image that needs internet access at run time.
Pre-built Controller Configurations
The configs/ directory includes a ready-to-use TOML file per image type:
| File | Use Case |
|---|---|
xrdp.toml | Desktop images with XRDP remote access |
xrdp_slurmController.toml | Desktop images that are also Slurm controllers |
terminal.toml | Terminal-only images (no GUI) |
slurmController.toml | Slurm controller nodes |
slurmWorker.toml | Slurm worker nodes |
clusterController.toml | Cluster controller nodes |
See Controller Configuration for parameter details.