Service Configuration

Last updated: August 20, 2026Latest Frontend Version: 2.17.7

Configuration Files

All configuration files use HOCON format and are located in /etc/ticrypt/. Each service has its own .conf file named after the service (e.g., ticrypt-rest.conf).

Each service has its own configuration file and options. Two services have more complex configuration and are documented on their own pages:

ticrypt-auth: Authentication, sessions, MFA, key escrow
ticrypt-vm: Realms, cost functions, hardware profiles

Value Types

Type	Example	Description
String	`"an example"`	String value
Bool	`true`, `false`	Boolean value
Int	`42`	Whole number value
Port	`22`	Number between 0 and 65535
Range	`"5000-5010"`	Range of ports
Duration	`1 minute`, `3 days`	Duration with unit of measure
Size	`16 MiB`, `3 GB`	File size with unit of measure
ArrPort	`[5000, 5002, 5005]`	Array of port values
ArrString	`["a", "b", "c"]`	Array of string values
ArrNET	`[172.24.0.0/16]`	Array of IP network CIDR ranges

Shared Sections

All services require the following sections. The configuration is identical across services unless noted otherwise.

`mongodb` Section

All tiCrypt services use MongoDB as their database. Each service has its own database with its own connection settings. See MongoDB Configuration for additional detail.

Parameter	Type	Description
`database`	String	MongoDB database name
`hostname`	String	MongoDB server hostname
`port`	Port	MongoDB server port
`user`	String	MongoDB username
`password`	String	MongoDB password

Alternatively, use a single uri parameter:

uri = "mongodb://user:password@localhost:27017/${database}"

warning

Do not specify both uri and individual connection parameters. Use one method or the other.

`ticrypt.auth` Section

All services must know how to contact the ticrypt-auth supervisor service:

Parameter	Type	Required	Description
`hostname`	String		Hostname where `ticrypt-auth` is running
`port`	Port		Port on which `ticrypt-auth` listens

Akka Parameters

Services use the Akka framework for inter-service communication. Two parameters control the Akka Artery transport:

Parameter	Description
`akka.remote.artery.canonical.hostname`	Interface to listen on. Use `127.0.0.1` if all services run on a single server.
`akka.remote.artery.canonical.port`	Listening port. Keep the default for each service to avoid port collisions.

`ticrypt-rest`

Parameters for the ticrypt.rest section in ticrypt-rest.conf:

Parameter	Type	Required	Description
`mongodb`	Section	✅	See mongodb
`http.host`	String		Interface to bind the HTTP server to
`http.port`	Port		Port for the HTTP server
`allowed-origins`	ArrString		Allowed CORS origins. An empty list permits all origins.
`vm.internal-networks`	ArrNET	✅	Internal network ranges for VM communication
`validation.request-json`	on, off	✅	Validate incoming JSON request bodies
`validation.response-json`	on, off	✅	Validate outgoing JSON response bodies
`session.search-raw-header`	Bool		Enable raw header search for session cookies. Turn on if sessions fail due to cookie parsing issues.

`akka.http.server` Section

HTTP server parameters for ticrypt-rest:

Parameter	Type	Default	Description
`parsing.max-content-length`	Size	`16 MiB`	Maximum request body size
`request-timeout`	Duration		Maximum duration for a single request
`idle-timeout`	Duration		Maximum idle time before closing the connection
`pipelining-limit`	Int		Maximum concurrent pipelined requests

tip

parsing.max-content-length must be at least 50% larger than the file chunk size. The default 16 MiB is recommended.

warning

idle-timeout must be longer than request-timeout. Setting them equal or reversed causes premature connection drops.

`ticrypt-file-manager`

Parameters for the ticrypt.filemanager section in ticrypt-file-manager.conf:

Parameter	Type	Required	Default	Description
`mongodb`	Section	✅		See mongodb
`chunk-size`	Size		`8 MiB`	Size of file storage chunks
`max-header-size`	Int		`64`	Maximum header size in bytes
`akka.remote.artery.canonical.hostname`				See Akka
`akka.remote.artery.canonical.port`				See Akka

warning

Changing max-header-size from the default of 64 bytes is not recommended. The default accommodates future changes to the header format.

`ticrypt-storage`

Parameters for the ticrypt.storage section in ticrypt-storage.conf:

Parameter	Type	Required	Description
`path`	String	✅	Absolute path to the file storage directory
`idle-time`	Duration		How long to wait before closing an idle connection
`idle-check`	Duration		How often to check for idle connections
`akka.remote.artery.canonical.hostname`			See Akka
`akka.remote.artery.canonical.port`			See Akka

`ticrypt-proxy`

Parameters for the ticrypt.proxy section in ticrypt-proxy.conf:

Parameter	Type	Required	Description
`interface`	String	✅	Interface/domain to listen on
`ports`	ArrPort	✅	Ports to use for proxying (supports ranges, e.g., `["6000-6010"]`)
`proxy-ttl`	Duration		How long to wait for a proxy connection
`akka.remote.artery.canonical.hostname`			See Akka
`akka.remote.artery.canonical.port`			See Akka

Security

The interface parameter is critical. Listen only on the domain used for proxying. Listening on the wrong interface can introduce security vulnerabilities.

note

The ports specified by ports must be open in the firewall for external access. Coordinate firewall rules with this setting.

`ticrypt-logger`

Parameters for the ticrypt.logger section in ticrypt-logger.conf:

Parameter	Type	Required	Description
`drivers`	Section	✅	Log output drivers. See Drivers.
`rotate-log`	on, off		Enable log rotation
`rotate-log-frequency`	Duration		How often to rotate logs
`rotate-log-suffix-format`	String		Log rotation suffix format (Joda DateTimeFormat)
`rotate-log-suffix-timezone`	String		Timezone for log rotation suffix (default: UTC)
`max-buffered-lines`	Int		Maximum log lines to buffer in memory
`akka.remote.artery.canonical.hostname`			See Akka
`akka.remote.artery.canonical.port`			See Akka

tip

In most deployments, max-buffered-lines is the only parameter that needs tuning. Increase it if log writes cause measurable I/O latency.

Log Drivers

The drivers section defines where logs are written. A typical setup uses two drivers:

drivers {
    main-file-logger {
        main = true
        immutable = true
        type = "file"
        log-file = "/var/log/ticrypt/ticrypt-secure-log.log"
    }
    tcp-logger {
        immutable = false
        main = false
        type = "tcp"
        host = "localhost"
        port = 25000
        send-timeout = 30s
        retry-timeout = 5s
    }
}

Driver	Purpose
`main-file-logger`	Master copy of the log, stored locally. The `immutable = true` flag produces append-only output.
`tcp-logger`	Forwards logs to a remote receiver (typically tiCrypt Audit) via TCP.

warning

Changing immutable to false disables append-only protection. Changing main to false removes the primary log output. Either change can result in unrecoverable audit gaps.

`ticrypt-stats`

Parameters for the ticrypt.stats section in ticrypt-stats.conf:

Parameter	Description
`akka.remote.artery.canonical.hostname`	See Akka
`akka.remote.artery.canonical.port`	See Akka

`ticrypt-notifications`

Parameters for the ticrypt.notifications section in ticrypt-notifications.conf:

Parameter	Description
`akka.remote.artery.canonical.hostname`	See Akka
`akka.remote.artery.canonical.port`	See Akka

`ticrypt-maintenance`

Parameters for the ticrypt.maintenance section in ticrypt-maintenance.conf:

Parameter	Type	Description
`account-locker`	Section	See Account Locker
`garbage-collector`	Section	See Garbage Collector
`backup-garbage-collector`	Section	See Backup Garbage Collector
`file-transfer-garbage-collector`	Section	See File Transfer Garbage Collector
`snapshot-garbage-collector`	Section	See Snapshot Garbage Collector
`drive-garbage-collector`	Section	See Drive Garbage Collector
`slurm-job-cleaner`	Section	See SLURM Job Cleaner
`deleted-user-cleanup`	Section	See Deleted User Cleanup
`akka.remote.artery.canonical.hostname`		See Akka
`akka.remote.artery.canonical.port`		See Akka

Account Locker

Automatically locks user accounts after a period of inactivity.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable automatic account locking
`frequency`	Duration	`4h`	How often to scan for inactive accounts
`time-before-account-old`	Duration	`365d`	How long an account must be inactive before it is locked

Garbage Collector

Removes orphaned files and directories (e.g., homes of deleted users) that no longer belong to any directory.

Parameter	Type	Default	Description
`enabled`	Bool	`false`	Enable the file garbage collector
`retention-period`	Duration	`60d`	Files older than this are eligible for deletion
`amount-grouped`	Int	`100`	Files are processed in batches of this size
`frequency`	Duration	`4h`	How often to run the garbage collector

Backup Garbage Collector

Removes old backup points after a retention period.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable backup point cleanup
`retention-period`	Duration		Backups older than this are deleted. If undefined, backups are kept indefinitely.
`frequency`	Duration	`4h`	How often to run the backup garbage collector

File Transfer Garbage Collector

Removes completed or stale file transfers.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable file transfer cleanup
`retention-period`	Duration		Transfers older than this are deleted. If undefined, transfers are kept indefinitely.
`frequency`	Duration	`4h`	How often to run the file transfer garbage collector

Snapshot Garbage Collector

Removes committed or unused snapshots. Snapshots are first moved to a trash directory before permanent deletion.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable snapshot cleanup
`retention-period`	Duration		Snapshots older than this are eligible for removal. If undefined, snapshots are kept indefinitely.
`trash-directory`	String		Directory where snapshots are moved before final deletion. Required for the garbage collector to run.
`trash-retention`	Duration		How long snapshots remain in the trash directory before permanent deletion. Required for the garbage collector to run.
`frequency`	Duration	`4h`	How often to run the snapshot garbage collector

Drive Garbage Collector

Removes drives from deleted users. Only drives with zero keys are removed.

Parameter	Type	Default	Description
`enabled`	Bool	`false`	Enable drive cleanup
`frequency`	Duration	`4h`	How often to run the drive garbage collector
`trash-directory`	String		Directory where drives are moved before final deletion. Required for the garbage collector to run.
`log`	Bool	`true`	Whether to log drives marked for deletion
`dry-run`	Bool	`false`	If true, only logs drives that would be deleted without actually moving them

SLURM Job Cleaner

Cleans up stale SLURM batch jobs.

Parameter	Type	Default	Description
`enabled`	Bool	`false`	Enable SLURM job cleanup
`frequency`	Duration	`1m`	How often to run the job cleaner
`stale-period`	Duration	`10m`	How long since cleanup started before a job is considered stale
`grace-period`	Duration	`10m`	How long to wait after a job is created before it can be deleted

Deleted User Cleanup

Permanently removes deleted user records from the system after a retention period.

Parameter	Type	Default	Description
`enabled`	Bool	`true`	Enable deleted user cleanup
`frequency`	Duration	`4h`	How often to run the cleanup task
`time-before-removal`	Duration	`365d`	How long since deletion before a user is permanently removed

`ticrypt-backup`

Parameters for the ticrypt.backup section in ticrypt-backup.conf:

Parameter	Type	Required	Default	Description
`mongodb`	Section	✅		See mongodb
`identifier`	String		`"ticrypt"`	Prefix used for backup directory names
`backup-base`	String	✅	`/storage/ticrypt/ticrypt-backup`	Directory where backups are stored locally
`storage-base`	String	✅	`/storage/ticrypt/ticrypt-storage`	Directory where files are located. Must match the `ticrypt-storage` path.
`num-copy-actors`	Int		`1`	Parallelism for file copying. Larger values may improve performance on fast file systems.
`max-attempts`	Int		`5`	Maximum attempts to copy a file before giving up
`sqlite.wal`	on, off		`off`	Whether to use SQLite3 write-ahead-log mode
`public-key-location`	String		`/var/lib/ticrypt/.ssh/id_rsa.pub`	Location of the tiCrypt public key for SFTP backup transfers
`path-translations`	Section			Maps host paths to backend paths. Must match `ticrypt-vm` path translations.
`akka.remote.artery.canonical.hostname`				See Akka
`akka.remote.artery.canonical.port`			`2564`	See Akka

warning

The path-translations section must match the translations configured in ticrypt-vm.conf. Mismatched translations will cause backup and restore operations to target incorrect paths.

`ticrypt-batch`

Parameters for the ticrypt.batch section in ticrypt-batch.conf. Manages SLURM batch job integration.

Parameter	Type	Required	Default	Description
`mongodb`	Section	✅		See mongodb
`check-ping-freq`	Duration		`2s`	How often to check for services that have not responded
`ping-timeout`	Duration		`20s`	How long a service can go without responding before being considered offline
`job-cleanup-period`	Duration		`30s`	How often to clean up completed or stale jobs
`slurm.user`	String	✅	`"ticrypt"`	System user under which SLURM commands are executed
`slurm.hostname`	String		`"localhost"`	Hostname of the SLURM controller
`slurm.token`	String	✅	`/etc/ticrypt/slurm-token`	Path to the SLURM authentication token file

`ticrypt-vmhost`

The ticrypt-vmhost.conf file uses shell environment variable format (KEY=VALUE), not HOCON. It configures the host controller service on each VM host server.

Parameter	Type	Required	Default	Description
`TICRYPT_BACKEND_IP`	String	✅	`127.0.0.1`	IP address of the tiCrypt backend server
`TICRYPT_BACKEND_NAME`	String	✅		Hostname of the tiCrypt backend server
`TICRYPT_REALM`	String	✅		The realm this host server belongs to
`TICRYPT_TOKEN`	String	✅		Realm token used for self-registration
`TICRYPT_HARDWARE_PROFILE`	String	✅		Hardware profile ID for this host server
`SSH_ALLOWED_NETWORK`	String		`0.0.0.0/0`	Network CIDR allowed for SSH connections (backend always included)
`NFS_HOST_IP`	String			IP address of the NFS host
`NFS_HOST_INTERNAL_NAME`	String		`nfs.ticrypt`	Hostname of the NFS host as seen from within VMs
`SECURE_FORWARD_BASE_PORT`	Int		`6000`	Base port number for secure tunnel forwards
`SECURE_NETWORK_PREFIX`	String	✅	`192.168.122`	IP prefix for the secure VM network (?.?.? format)
`SERVICE_NETWORK_PREFIX`	String	✅	`192.168.123`	IP prefix for the service VM network
`HOST_NETWORK_INTERFACE`	String	✅	`eth0`	Network interface facing the tiCrypt backend
`LIBVIRT_STORAGE`	String	✅	`/storage`	Path to the Libvirt storage directory
`LIBVIRT_USER`	String		`ticrypt`	System user for Libvirt operations
`LIBVIRT_NETWORK_TYPE`	String		`route`	Type of Libvirt network

info

This file is deployed to each VM host, not on the backend server. It is sourced by the host controller service at startup.

Value Types​

Shared Sections​

mongodb Section​

ticrypt.auth Section​

Akka Parameters​

ticrypt-rest​

akka.http.server Section​

ticrypt-file-manager​

ticrypt-storage​

ticrypt-proxy​

ticrypt-logger​

Log Drivers​

ticrypt-stats​

ticrypt-notifications​

ticrypt-maintenance​

Account Locker​

Garbage Collector​

Backup Garbage Collector​

File Transfer Garbage Collector​

Snapshot Garbage Collector​

Drive Garbage Collector​

SLURM Job Cleaner​

Deleted User Cleanup​

ticrypt-backup​

ticrypt-batch​

ticrypt-vmhost​

Value Types

Shared Sections

`mongodb` Section

`ticrypt.auth` Section

Akka Parameters

`ticrypt-rest`

`akka.http.server` Section

`ticrypt-file-manager`

`ticrypt-storage`

`ticrypt-proxy`

`ticrypt-logger`

Log Drivers

`ticrypt-stats`

`ticrypt-notifications`

`ticrypt-maintenance`

Account Locker

Garbage Collector

Backup Garbage Collector

File Transfer Garbage Collector

Snapshot Garbage Collector

Drive Garbage Collector

SLURM Job Cleaner

Deleted User Cleanup

`ticrypt-backup`

`ticrypt-batch`

`ticrypt-vmhost`