Libvirt Realms

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

The Libvirt realm uses KVM/QEMU to control VMs. Realm configuration is defined in a file included from the realms section of ticrypt-vm.conf.

Prerequisites

Libvirt realms require:

1. Root SSH access from ticrypt-vm to all VM hosts (RSA-2048 public key injected into /root/.ssh/authorized_keys on each host)
2. A distributed file system shared by all VM hosts, large enough for VM images, drives, and Libvirt temporary files

See the Installation Guide for host preparation and Libvirt pool setup.

Realm Parameters

All parameters go in the included realm file and should not be nested inside additional sections.

Parameter	Type	Required	Default	Description
disabled	Boolean	✅		Whether the realm is disabled
driver	libvirt	✅		Must be set to libvirt
name	String	✅		Display name of the realm
volumes-pool	String		ticrypt-vm	Libvirt storage pool for volumes
drives-pool	String		ticrypt-vm-drives	Libvirt storage pool for drives
bricks-pool	String		ticrypt-bricks	Libvirt storage pool for VM images
log-scheduling	Boolean		false	Enable debug logging for the VM scheduler
registration-timeout	Duration			Maximum time for a VM to boot and register
poll-frequency	Duration			How often to check VM status
network-filter	String			Libvirt network filter. See nwfilter docs.
drives.lazy-allocation	on, off	✅		Whether to delay drive space allocation
drives.cache	String		"default"	Drive cache strategy (see below)
drives.min-size	Size			Minimum allowed drive size
drives.max-size	Size			Maximum allowed drive size
uploads	Section			Reserved for future use
scaling	Section			Reserved for future use

info

The default pool names are sufficient for single-instance deployments. Change them only when multiple tiCrypt instances share the same Libvirt infrastructure.

warning

Do not set registration-timeout too short. VMs that cannot boot and register within this window are terminated.

tip

Set drives.lazy-allocation to on in nearly all cases. Storage space is consumed only as data is written, rather than being fully allocated upfront.

Drive Cache Strategies

The drives.cache parameter controls how the host OS caches drive I/O. Leave it at "default" unless you have a specific reason to change it.

Value	Behavior
"default"	System default. May be writethrough or writeback depending on the qemu-kvm version.
"writethrough"	Host page cache enabled, disk write cache disabled. Writes complete only when committed to storage. Similar to O_DSYNC.
"writeback"	Both host page cache and disk write cache enabled. Behaves like a RAID controller with RAM cache.
"none"	Bypasses host page cache entirely. Similar to O_DIRECT.

Example Realm Configuration

disabled = false
driver = libvirt
name = "Primary Libvirt Realm"
volumes-pool = "ticrypt-vm"
drives-pool = "ticrypt-vm-drives"
bricks-pool = "ticrypt-bricks"
registration-timeout = 5 minutes
poll-frequency = 30 seconds
drives.lazy-allocation = on
drives.cache = "default"
drives.max-size = 500 GiB

All three pools share the same underlying distributed file system.

Related Configuration

The following are configured at the service level in ticrypt-vm.conf and apply across all realms:

• Cost Functions: Rules that determine scheduling cost for VM placement
• Hardware Profiles: Hardware descriptions assigned to hosts
• Hosts: Individual machines managed via the tiCrypt UI
• Curves: Built-in functions used within cost functions