VM Service (ticrypt-vm)

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

Configuration File

/etc/ticrypt/ticrypt-vm.conf. All options are in the ticrypt.vm section.

Service Parameters

Parameter	Type	Required	Description
`mongodb`	Section	✅	Database connection. See mongodb.
`cost-functions`	Section	✅	VM scheduling cost rules. See Cost Functions.
`hardware-profiles`	Section	✅	Hardware descriptions for hosts. See Hardware Profiles.
`realms`	Section	✅	VM execution environments. See Realms.
`licensing-server-driver`	String		Firewall driver: `none` or `firewalld`
`reload-freq`	Duration		How often to rebuild firewall rules
`firewalld`	Section		Required if `licensing-server-driver` is `firewalld`
`akka.remote.netty.tcp.hostname`			See Akka
`akka.remote.netty.tcp.port`			See Akka

Firewalld

If using the firewalld licensing server driver:

Parameter	Type	Required	Description
`file-access`	String	✅	File where firewall rules are written

warning

The file-access path must match the mechanism that transforms rules into firewall access. If using the ticrypt-allowedlist service, set this to /etc/ticrypt/allowedlist.txt.

Realms

A realm is a fully independent VM execution environment with its own VM images and drives.

The realms section includes configuration files for each realm:

realms {
    libvirt1 = { include "realms/libvirt1.conf" }
    libvirt2 = { include "realms/libvirt2.conf" }
}

You can define multiple realms. Each realm file contains parameters documented on the Libvirt Realms page.

Hardware Specification

There are four components in VM host hardware configuration:

Component	Description	Managed In
Curves	Built-in functions that compute a scheduling cost from a single attribute (VM count, memory, device count)	`ticrypt-vm.conf`
Cost Functions	Rules combining multiple curves to determine total scheduling cost for a host	`ticrypt-vm.conf`
Hardware Profiles	Hardware descriptions linking a cost function with resource information	`ticrypt-vm.conf`
Hosts	Individual machines that run VMs, each assigned a hardware profile	tiCrypt UI

Each host is assigned a hardware profile.
The hardware profile references a cost function.
The cost function evaluates curves for VM count, vCPUs, memory, and devices to produce a total cost.
The scheduler selects the host with the lowest cost.

Value Types

Type	Example	Description
String	`"an example"`	String value
Int	`42`	Whole number value
Bytes	`32`, `64 MiB`, `18 GiB`	Number with optional byte unit
Real	`1.0`, `1`	Real number with optional decimal
RealOrBytes	`1.0`, `32 MiB`, `2 GiB`	Real number or byte value with unit
Curve	`{curve: invalid}`	A curve definition
CurveMap	`{id1: {...}, id2: {...}}`	Mapping of IDs to curve definitions
Device	`{type: "gpu", addr: "02:03.4"}`	Device type and PCI address
DeviceList	`[{...}, {...}]`	List of Device entries

Curves

Curves are configuration objects with a required curve parameter that selects a built-in function. The function takes a single numeric input (VM count, memory bytes, or device count) and returns a scheduling cost.

Common parameters (apply to all curve types):

Parameter	Type	Default	Description
`scale`	Real	`1.0`	Scale factor applied to the curve result
`max`	Real	None	Input values past this return infinity (prevents scheduling)

Constant Curve

Type: constant

Returns a fixed value regardless of input.

Parameter	Type	Required	Description
`value`	Real	✅	The constant value to return

{ curve: constant, value: 1.0 }

Invalid Curve

Type: invalid

Always returns positive infinity, preventing VMs from being scheduled. Useful in combination with the Piecewise Curve.

{ curve: invalid }

Linear Curve

Type: linear

Computes cost from a line with a given slope and base.

Parameter	Type	Required	Description
`slope`	RealOrBytes	✅	Slope of the line
`base`	RealOrBytes	✅	Value returned when input is 0

{ curve: linear, slope: 1.0, base: 0.0 }
{ curve: linear, slope: 10.0, base: 5.0 }

Hard-Soft Curve

Types: hard-soft, soft-hard

Piecewise linear curve with a soft cap and a hard cap. Cost ramps slowly until soft, then ramps steeply until hard. Past hard, cost is infinite (prevents scheduling).

Parameter	Type	Required	Default	Description
`soft`	RealOrBytes	✅		Input value at which `softAmt` is returned
`hard`	RealOrBytes	✅		Input value at which `hardAmt` is returned
`softAmt`	Real		`1.0`	Cost when input reaches `soft`
`hardAmt`	Real		`10.0`	Cost when input reaches `hard`

# Returns 0 at 0, 1 at 1, 10 at 2, infinity past 2
{ curve: "hard-soft", soft: 1.0, hard: 2.0 }

# These two are equivalent
{ curve: "hard-soft", soft: 32 GiB, hard: 48 GiB, softAmt: 10, hardAmt: 100 }
{ curve: "hard-soft", soft: 32 GiB, hard: 48 GiB, scale: 10.0 }

Unavailable Curve

Type: unavailable

Returns 0 if input is zero or less, infinity otherwise. This is the default curve for any devices without explicit curve definitions.

{ curve: unavailable }

Piecewise Curve

Types: piecewise, low-high, high-low

Returns the result of one of two sub-curves depending on whether the input is below or above a cutoff. Enables complex cost functions.

Parameter	Type	Required	Description
`cutoff`	RealOrBytes	✅	Threshold for switching from `low` to `high` curve
`low`	Curve	✅	Curve used when input ≤ cutoff
`high`	Curve	✅	Curve used when input > cutoff

# Constant cost of 5 up to a hard cutoff at 6
{ curve: piecewise, cutoff: 6.0, low: { curve: constant, value: 5}, high: { curve: invalid } }

Nested piecewise example (equivalent to hard-soft with soft=1, hard=2):

{
    curve: piecewise
    cutoff: 1
    low: {
        curve: linear
        slope: 1
        base: 0
    }
    high: {
        curve: piecewise
        cutoff: 2
        low: {
            curve: linear
            slope: 9
            base: -8
        }
        high: {
            curve: invalid
        }
    }
}

Cost Functions

Cost functions are defined in the ticrypt.vm.cost-functions section. Each entry maps an ID to a definition that combines curves for different resource types.

Parameter	Type	Default	Description
`name`	String	Same as ID	Human-readable name
`description`	String	Empty	Description of the cost function
`vms`	Curve	None	Cost based on number of running VMs
`vcpus`	Curve	None	Cost based on virtual CPU cores in use
`memory`	Curve	None	Cost based on memory usage in bytes
`devices`	CurveMap	None	Per-device-type cost curves (keyed by device ID)
`scale`	Real	`1.0`	Multiplier applied to all costs
`offset`	Real	`0.0`	Static cost added after scaling

note

Device types not listed in devices default to the unavailable curve.

warning

At least one of vms, vcpus, or memory must define a curve. Without any resource curve, VMs using no devices have no scheduling restriction, which causes rapid resource exhaustion.

Examples

Basic cost function:

ticrypt.vm.cost-functions {
    simple {
        name: "Simple"
        description: "A basic cost function"

        vms: { curve: "linear", slope: 1, base: 0 }
        vcpus: { curve: "hard-soft", soft: 8, hard: 16, softAmt: 4, hardAmt: 32 }
        memory: { curve: "hard-soft", soft: 16 GiB, hard: 32 GiB, scale: 10 }
    }
}

Cost function with GPU devices:

ticrypt.vm.cost-functions {
    nvidia-gpu {
        name: "GPU Node"
        description: "Used for GPU nodes with the standard configuration"

        vms: { curve: "linear", slope: 1, base: 0 }
        vcpus: { curve: "hard-soft", soft: 8, hard: 16, softAmt: 4, hardAmt: 32 }
        memory: { curve: "hard-soft", soft: 16 GiB, hard: 32 GiB, scale: 10 }

        devices.nvidia-gpu: { curve: linear, slope: 1, base: 0, max: 2 }

        # High offset so VMs prefer non-GPU hosts when possible
        offset: 100000
    }
}

Shared cost functions using includes:

ticrypt-vm.conf:

ticrypt.vm.cost-functions {
    pool1 {
        include "cost-functions/pool-common.conf"
        name: "Pool 1"
    }
    pool2 {
        include "cost-functions/pool-common.conf"
        name: "Pool 2"
        offset: 1000
    }
}

cost-functions/pool-common.conf:

vms: { curve: "linear", slope: 1, base: 0 }
vcpus: { curve: "hard-soft", soft: 8, hard: 16, softAmt: 4, hardAmt: 32 }
memory: { curve: "hard-soft", soft: 16 GiB, hard: 32 GiB, scale: 10 }

Hardware Profiles

Hardware profiles are defined in ticrypt.vm.hardware-profiles. Each profile maps an ID to a hardware description linked to a cost function.

Parameter	Type	Required	Default	Description
`name`	String		Same as ID	Human-readable name
`description`	String		Empty	Description of the hardware profile
`cores`	Int	✅		CPU cores available on the host
`memory`	Bytes	✅		Memory available on the host
`devices`	DeviceList		`[]`	PCI devices available for VM passthrough
`cost-function`	String	✅		ID of the cost function to use

Examples

ticrypt.vm.hardware-profiles {
    pool1: {
        name: "Pool 1"
        description: "Standard host in pool 1"
        cores: 8
        memory: 32 GiB
        cost-function: "pool1"
    }

    pool2: {
        name: "Pool 2"
        description: "Standard host in pool 2"
        cores: 8
        memory: 32 GiB
        cost-function: "pool2"
    }

    nvidia-gpu-node: {
        name: "NVidia GPU Node"
        description: "Special nodes with NVidia GPUs attached"
        cores: 8
        memory: 32 GiB
        cost-function: nvidia-gpu
        devices = [
            {type: "nvidia-gpu", addr: "0000:01:02.0"}
            {type: "nvidia-gpu", addr: "02:03.0"}
        ]
    }
}

Hosts

Hosts are managed from the Management section in the tiCrypt user interface. Administrators can add, enable, disable, and remove hosts.

Each host requires:

Name A descriptive name for the host.

URI The Libvirt connection URI. See Libvirt URI documentation for all formats.

Connection Type	URI Format
Local QEMU	`qemu:///system`
Remote QEMU	`qemu+ssh://[user@]host[:port]/system`

Hardware Profile One of the defined hardware profiles.

State

State	Behavior
Enabled	Connected to host, VMs scheduled normally
No Scheduling	Connected to host, but no new VMs scheduled. Existing VMs can still be managed. Useful for graceful node maintenance.
Disabled	No connection made, no VMs scheduled

Static Address Translation Optional. Used when VMs are on networks not directly reachable from the tiCrypt server. Specify an IP address and base port; tiCrypt connects to the translated address with port = base port + last octet of the VM's IP.

Service Parameters​

Firewalld​

Realms​

Hardware Specification​

Value Types​

Curves​

Constant Curve​

Invalid Curve​

Linear Curve​

Hard-Soft Curve​

Unavailable Curve​

Piecewise Curve​

Cost Functions​

Examples​

Hardware Profiles​

Examples​

Hosts​

Service Parameters

Firewalld

Realms

Hardware Specification

Value Types

Curves

Constant Curve

Invalid Curve

Linear Curve

Hard-Soft Curve

Unavailable Curve

Piecewise Curve

Cost Functions

Examples

Hardware Profiles

Examples

Hosts