Service Configuration

Last updated: May 29, 2026Latest Frontend Version: 2.16.20

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 of the ten services 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

Almost all services require the following sections. The configuration is virtually identical across services.

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	Required	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 TCP transport:

Parameter	Description
akka.remote.netty.tcp.hostname	Interface to listen on. Use 127.0.0.1 if all services run on a single server.
akka.remote.netty.tcp.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. 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 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 will cause 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 GiB	Size of file storage chunks
max-header-size	Int		64	Maximum header size in bytes
akka.remote.netty.tcp.hostname				See Akka
akka.remote.netty.tcp.port				See Akka

warning

Changing max-header-size from the default of 64 bytes is not recommended. The default future-proofs the tiCrypt instance against header format changes.

---

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.netty.tcp.hostname			See Akka
akka.remote.netty.tcp.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	ArrPorts	✅	Ports to use for proxying (supports ranges, e.g., ["6000-6010"])
proxy-ttl	Duration		How long to wait for a proxy connection
akka.remote.netty.tcp.hostname			See Akka
akka.remote.netty.tcp.port			See Akka

Security

The interface parameter is critical. You must listen only on the domain used for proxying. Listening on the wrong interface can open 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.netty.tcp.hostname			See Akka
akka.remote.netty.tcp.port			See Akka

tip

The only parameter you should typically adjust is max-buffered-lines, and only if you observe performance degradation from log writes.

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

Do not modify the main-file-logger configuration without careful consideration. Incorrect settings can result in a non-functioning logging system.

---

ticrypt-stats

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

Parameter	Description
akka.remote.netty.tcp.hostname	See Akka
akka.remote.netty.tcp.port	See Akka

---

ticrypt-notifications

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

Parameter	Description
akka.remote.netty.tcp.hostname	See Akka
akka.remote.netty.tcp.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
akka.remote.netty.tcp.hostname			See Akka
akka.remote.netty.tcp.port			See Akka

Account Locker

Automatically locks user accounts after a period of inactivity.

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