VM Image Troubleshooting

Last updated: July 31, 2026Latest Frontend Version: 2.17.4

If a VM 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.

Verification Checklist

Windows

Log in as Administrator via VNC and verify:

Check	How	Expected
Network	ipconfig	IPv4 address assigned via DHCP
VM Installer service	Get-Service ticrypt-vm-controller	Running
Service logs	Event Viewer > Application log	No controller registration or download errors
SSH disabled	Get-Service sshd	Stopped / Disabled. If running, it is blocking port 22
VirtIO drivers	Device Manager	No missing devices or driver warnings

Linux

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

RDP Troubleshooting (Linux)

If the VM Controller registers successfully but RDP connections fail, check the appropriate section below based on your remote desktop configuration.

XRDP (Rocky 8/9)

Check	Command	Expected
XRDP service	systemctl status xrdp	Active, listening on port 3389
XRDP sesman	systemctl status xrdp-sesman	Active, no errors
Port binding	ss -tlnp | grep 3389	xrdp process listening
XRDP logs	cat /var/log/xrdp-sesman.log	No session startup or authentication errors
D-Bus	systemctl status dbus	Active
SELinux denials	ausearch -m avc -ts recent	No denials related to xrdp, Xorg, or /tmp/.X11-unix
Startup ordering	systemctl cat xrdp-sesman	Drop-in shows After=dbus.service network-online.target

The most common cause of intermittent XRDP failures is a missing systemd startup ordering override. If xrdp-sesman starts before D-Bus or NFS mounts are ready, connections fail non-deterministically. See the XRDP configuration guide for the required drop-in overrides.

GNOME Remote Desktop (Rocky 10+)

GRD uses headless mode with per-user provisioning via a controller.toml hook. Replace <user> with the tiCrypt-provisioned username.

Check	Command	Expected
GDM service	systemctl status gdm	Active
Headless session	systemctl status gnome-headless-session@<user>	Active
Boot target	systemctl get-default	graphical.target (not multi-user.target)
Port binding	ss -tlnp | grep 3389	gnome-remote-d process listening
GRD status	sudo -u <user> XDG_RUNTIME_DIR=/run/user/$(id -u <user>) grdctl --headless status	RDP enabled, valid TLS cert paths
User linger	ls /var/lib/systemd/linger/<user>	File exists
SELinux denials	ausearch -m avc -ts recent	No denials related to gnome-remote-desktop, gdm, mutter
Startup ordering	systemctl cat gdm	Drop-in shows After=dbus.service network-online.target
Provisioning script	ls -la /usr/local/bin/ticrypt-grd-provision.sh	Exists and is executable

The most common GRD issues are: (1) a missing graphical.target default, which prevents GDM from starting; (2) a missing or non-executable provisioning script; (3) SELinux denials blocking the headless session. See the GNOME Remote Desktop guide for the required configuration.

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