tiCrypt

Service Configuration

Each backend service reads its settings from its own file in /etc/ticrypt/, named for the service: ticrypt-auth.conf, ticrypt-rest.conf, and so on. The files use HOCON format, except ticrypt-vmhost.conf, which is a shell environment file. A parameter that is commented out or absent takes the default shown in the tables below.

The sections that several services share are described first, followed by the settings of each service. Two services have more options 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

These sections take the same parameters in every service that has them.

mongodb Section

Five services store their data in MongoDB: ticrypt-auth, ticrypt-file-manager, ticrypt-vm, ticrypt-batch, and ticrypt-notifications. Each has its own database and its own connection settings, inside the service's own section (for example ticrypt.auth.mongodb). The other services keep no database. See MongoDB Configuration for additional detail.

Parameter	Type	Default	Description
database	String	Named for the service, for example ticrypt-auth	MongoDB database name
hostname	String	localhost	MongoDB server hostname
port	Port	27017	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

Every service other than ticrypt-auth itself must know how to contact the ticrypt-auth supervisor service. This section sits at the top level of the file, beside the service's own section, not inside it.

Parameter	Type	Default	Description
hostname	String	127.0.0.1	Hostname where ticrypt-auth is running
port	Port	2552	Port on which ticrypt-auth listens

Akka Parameters

Services use the Akka framework for inter-service communication. Two parameters inside each service's own section control the Akka Artery transport:

Parameter	Description
akka.remote.artery.canonical.hostname	Interface to listen on. The default is 127.0.0.1, which is correct when all services run on a single server.
akka.remote.artery.canonical.port	Listening port. Keep the default for each service to avoid port collisions.

Each service has its own default port:

Service	Default port
ticrypt-auth	2552
ticrypt-rest	2553
ticrypt-file-manager	2555
ticrypt-stats	2556
ticrypt-proxy	2557
ticrypt-logger	2559
ticrypt-vm	2560
ticrypt-notifications	2561
ticrypt-maintenance	2562
ticrypt-batch	2565

Log Level and JVM Options

Two more files in /etc/ticrypt/ apply to the Java process of a service, not to its tiCrypt settings. Both are kept on upgrade once edited.

File	Applies to	Purpose
logback.xml	Every backend service	Sets how much each service writes to the systemd journal. Shipped from 3.16.2, with the root level at INFO.
<service>.jvmopts	One service	JVM startup options, one per line. The shipped files set the heap to -Xms1g -Xmx2g and the thread stack to -Xss2m.

To get debug output while troubleshooting, set the root level in logback.xml to DEBUG, or add a <logger> element for one package, and restart the service. Set it back to INFO afterwards: at DEBUG, libraries write request details into the journal.

<root level="INFO">
    <appender-ref ref="CONSOLE"/>
</root>

Raise -Xmx in a service's .jvmopts file when that service runs out of memory. Java 21 refuses to start with options that only Java 8 accepted; see Java 21 from backend 3.15.0.

---

ticrypt-rest

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

Parameter	Type	Required	Default	Description
http.host	String		localhost	Interface to bind the HTTP server to
http.port	Port		8080	Port for the HTTP server
backend-timeout	Duration		5m	How long to wait for a request to another backend service before timing out
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		on	Scan incoming JSON request bodies for HTML and other structures that could be used for reflection attacks
validation.response-json	on, off		on	Scan outgoing JSON responses the same way, so that such content is not served even if the database is compromised
session.search-raw-header	Bool		false	Enable raw header search for session cookies. Turn on if sessions fail due to cookie parsing issues.
storage	Section	✅		See storage

The section also takes the two Akka parameters; the default port is 2553.

storage Section

Parameters for ticrypt.rest.storage, where the encrypted Vault lives on disk.

Parameter	Type	Required	Default	Description
path	String	✅	/tmp/ticrypt-storage	Directory holding the encrypted file chunks. The installer sets this from global.storagePath in ticrypt.yml
max-writes	Int		1000	How many writes may be in flight at once

warning

path must point at persistent storage writable by the ticrypt user. The built-in default is under /tmp, which does not survive a reboot. Confirm this value on any deployment where the installer did not set it, and set ticrypt.filemanager.storage.path to the same storage.

note

ticrypt-setup also writes read.chunksize, write.print-stats, idle-time, idle-check, clean-workers-frequency, and min-response-time into this section. No current service reads them, so changing them does nothing.

akka.http.server Section

HTTP server parameters for ticrypt-rest. This section sits at the top level of ticrypt-rest.conf, outside ticrypt.rest.

Parameter	Type	Shipped value	Description
parsing.max-content-length	Size	16 MiB	Maximum request body size
request-timeout	Duration	20 minutes	Maximum duration for a single request
idle-timeout	Duration	25 minutes	Maximum idle time before closing the connection
pipelining-limit	Int	Commented out (16)	Maximum concurrent pipelined requests

The shipped file also sets akka.http.client.idle-timeout to 25 minutes.

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	Size		64 bytes	Extra bytes allowed per chunk for the headers used in decryption (IV, authentication tags)
storage.path	String	✅	/tmp/ticrypt-storage	Where file chunks are stored on disk. Must be the same storage as ticrypt.rest.storage.path, mounted on this host
akka.remote.artery.canonical.hostname				See Akka
akka.remote.artery.canonical.port			2555	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.

warning

The file manager deletes chunks under storage.path when files are deleted or purged. If the path does not match the one ticrypt-rest writes to, the chunks are silently left on disk. The file manager logs an error at startup when the path is not a directory.

---

ticrypt-proxy

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

Parameter	Type	Required	Default	Description
interface	String	✅	localhost	Interface/domain to listen on
ports	ArrPort	✅	[] in the shipped file	Ports to use for proxying. Accepts single ports and inclusive ranges, e.g., [ 6010-6015, 6025 ]
proxy-ttl	Duration		5 minutes	How long the client has to start a connection after a binding has been created
akka.remote.artery.canonical.hostname				See Akka
akka.remote.artery.canonical.port			2557	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	Default	Description
drivers	Section	✅		Log output drivers. See Drivers.
rotate-log	on, off		on	Enable log rotation
rotate-log-frequency	Duration		1 day	How often to rotate logs
rotate-log-suffix-format	String		'-'yyyyMMdd'T'HHmmss	Log rotation suffix format (Joda DateTimeFormat)
rotate-log-suffix-timezone	String		UTC	Timezone for log rotation suffix. Set to null to use the system timezone
max-buffered-lines	Int		10	Maximum log lines to buffer in memory
akka.remote.artery.canonical.hostname				See Akka
akka.remote.artery.canonical.port			2559	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. Exactly one driver must have main = true. The shipped file defines only the file driver; a typical setup adds a TCP driver:

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. send-timeout is how long to wait for an acknowledgment before sending a message again; retry-timeout is how long to wait before reconnecting.

Driver changes are reloaded when the logger service receives SIGHUP, except for drivers with immutable = true, which do not reload.

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
mongodb	See mongodb. Not in the shipped file; the default is the ticrypt-notifications database on localhost
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	Required	Description
account-locker	Section		See Account Locker
garbage-collector	Section		See 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	90d	How long an account must be inactive before it is locked

Garbage Collector

Reclaims files that no longer belong to any directory, such as the homes of deleted users. A file is a candidate when no directory entry anywhere links to it. Collection runs in two passes on separate schedules: a sweep moves unreferenced records to a trash collection, and a purge removes their keys, chunks, and records once the grace period has passed.

Rebuilt in 3.14.1. Before that release the sweep returned no candidates, so nothing was reclaimed.

Parameter	Type	Default	Description
enabled	Bool	false	Enable the file garbage collector. The collector is not created at all when false
dry-run	Bool	true	Log what would be collected and purged without changing anything. Restoring is the exception: every purge pass, dry-run or not, returns trashed files that a directory links to again
retention-period	Duration	60d	A file must be unreferenced and created longer ago than this before the sweep will mark it. Counted from the file's creation, not from when its last link was removed
amount-grouped	Int	100	Files are processed in batches of this size
frequency	Duration	4h	How often the sweep pass runs
purge-frequency	Duration	24h	How often the purge pass runs
deleted-grace-period	Duration	3d	How long a marked file sits in the trash collection before its keys, chunks, and record are removed
scan-timeout	Duration	30m	How long to wait for the initial file and directory scan before abandoning the pass
purge-timeout	Duration	30m	How long to wait for a live purge to report back. The purge keeps running if this expires; only its summary log line is lost
log-directory	String	/var/log/ticrypt/file-gc	Where dry-run logs are written. Created if missing, and a write failure is logged without failing the pass

Run multiple dry runs before going live

dry-run = true is the default and it must stay that way until you have read the candidate logs and confirmed that every file listed is genuinely unreachable. Run at least two or three full frequency cycles and read file-garbage-collector-<timestamp>.log after each one.

A purge removes keys and chunks. There is no undo, and no backup is taken first. Turning dry-run off before verifying the candidate list risks destroying research data that a reference-count bug or an in-progress migration made look unreferenced.

Why dry-run defaults to true

The purge is permanent: keys, chunks, and records are removed with no undo and no backup. If the default were false, a missing or overlooked config line would let the collector act on its first run, before an operator has verified the candidate list. Defaulting to true makes the collector inert until the operator has reviewed the logs across several cycles and explicitly opted in.

The drive garbage collector, by contrast, defaults dry-run to false because it moves drives to a trash directory before final deletion and only targets drives from deleted users with zero keys, giving operators a recovery path that the file purge does not have.

What happens when dry-run is turned off

With dry-run = false, the collector does exactly what the other parameters say, on their schedules:

ticrypt.maintenance.garbage-collector {
  enabled = true
  dry-run = false
  retention-period = 60d      # only unreferenced files created more than 60 days ago
  frequency = 4h              # the sweep marks them, in batches of amount-grouped
  deleted-grace-period = 3d   # they sit in the trash collection for 3 days
  purge-frequency = 24h       # the purge then removes keys, chunks, and records
}

retention-period counts from the file's creation, so a file older than 60 days is marked within one sweep of losing its last directory link. What protects it from then on is deleted-grace-period: nothing is destroyed sooner than that after it is marked. Shortening either value shortens the window in which a mistake can still be caught.

How the two periods interact, with worked timings, is in How the two waiting periods work. The full go-live procedure, including how to read the logs and spot-check candidates, is in Take the File Garbage Collector Live.

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. Until then, an admin can restore a deleted account from Management > Users > Deleted Users; once the cleanup has removed it, the account cannot be restored. Set time-before-removal to match your institution's retention policy. See Deleted Users.

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-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

The section also takes the two Akka parameters, which are not in the shipped file; the default port is 2565.

---

ticrypt-vmhost

The ticrypt-vmhost.conf file uses shell environment variable format (KEY=VALUE), not HOCON. The ticrypt-vmhost setup scripts read it to generate the libvirt network and storage definitions and the iptables rules of a VM host.

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		$TICRYPT_BACKEND_IP/32	Network, in CIDR format, allowed to SSH to this host. The backend is always allowed
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. The ticrypt-vmhost scripts source it each time they run, so run them again after changing a value.

SSH_ALLOWED_NETWORK from 3.16.2

A VM host set up from the 3.16.2 or later file allows SSH from the tiCrypt backend only. Set SSH_ALLOWED_NETWORK to an admin network such as 10.0.0.0/24 to allow SSH from it as well. Before 3.16.2 the shipped value was 0.0.0.0/0, and a host that keeps its existing file is unchanged by an upgrade.

Related

• Interactive Configuration Reference: search these parameters and filter them down to the required ones.
• Auth Service (ticrypt-auth): configure sessions, MFA, and key escrow, which are documented on their own page.
• VM Service (ticrypt-vm): configure realms, cost functions, and hardware profiles.
• MongoDB Configuration: set up the database that every mongodb section connects to.
• Take the File Garbage Collector Live: move the garbage collector configured here from dry-run to live safely.