tiCrypt 2.17.11

Service Configuration

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

Each backend service reads its settings from its own file in /etc/ticrypt/, named for the service: ticrypt-auth.conf, ticrypt-vm.conf, and so on. All of them use HOCON format.

Most sections are identical across every service, and those shared sections are described first. Settings specific to one service are on that service's own page. A value left commented out takes the default shown in the tables below.

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.

`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 reference default is under /tmp, which does not survive a reboot. Confirm this value on any deployment where the installer did not set it.

note

ticrypt-setup also writes read.chunksize, write.print-stats, idle-time, idle-check, clean-workers-frequency, and min-response-time into this section. They carry over from the removed ticrypt-storage service and have no effect. Changing them does nothing.

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

Removed in 3.13.2

ticrypt-storage was removed in 3.13.2 and is not installed or started on current deployments. The file storage directory is now set in ticrypt-rest as storage.path.

This section applies only to deployments running 3.13.1 or earlier. A ticrypt-storage.conf left behind by an upgrade has no effect.

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

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 older than this before the sweep will mark it
`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.

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 files unreferenced and older than 60 days
  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
}

Nothing is reclaimed sooner than retention-period plus deleted-grace-period after a file becomes unreferenced. Shortening either value shortens the window in which a mistake can still be caught.

The full go-live procedure, including how to read the logs and spot-check candidates, is in Backend 3.14.1.

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`

Removed in 3.13.2

ticrypt-backup was removed in 3.13.2 alongside ticrypt-storage, and is not installed or started on current deployments. Back up the storage directory with your own tooling. Every chunk is encrypted with keys only users hold, so the raw files can be copied to unencrypted backup targets without exposing data.

This section applies only to deployments running 3.13.1 or earlier.

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​

storage Section​

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`

`storage` Section

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