Configuration

Trident is configured with a single TOML file, installed by default at /etc/trident/config.toml. This page walks through each section of the default configuration.

Default Configuration

# Trident HTTP Cache Proxy - Default Configuration
#
# Multi-site: use includes to load site-specific configs:
#   include = ["sites-enabled/*.toml"]

[server]
listeners = [
    { address = "0.0.0.0:8120" }
]

# Uncomment to enable HTTPS:
# listeners = [
#     { address = "0.0.0.0:8120" },
#     { address = "0.0.0.0:8443", tls = true }
# ]

[server.timeouts]
connect = "5s"
header_read = "10s"
body_read = "60s"
idle_keepalive = "60s"
backend_connect = "5s"
backend_first_byte = "60s"
backend_between_bytes = "30s"

[server.limits]
max_connections = 10000
max_header_size = "32 KiB"
max_body_size = "10 MiB"
max_uri_length = 8192
max_headers = 100

# Backend origin server
[[backends]]
name = "origin"
address = "127.0.0.1:8080"

# Cache settings
[cache]
enabled = true
max_memory = "1 GiB"
grace_period = "60s"
stale_while_revalidate = true

# TTL settings
[ttl]
mode = "origin"       # "origin" = respect Cache-Control, "override" = ignore origin headers
default = "1h"
max = "24h"

# Admin API (bound to localhost only for security)
[admin]
enabled = true
address = "127.0.0.1:6085"

# Logging
[logging]
level = "info"
format = "json"

Section Reference

[server]

Defines listeners and protocol settings.

Key	Description
listeners	Array of listener objects with address and optional tls flag

Each listener binds to an address in host:port format. Set tls = true to enable HTTPS on that listener (requires TLS certificate configuration).

[server.timeouts]

Controls timeout durations for client and backend connections.

Key	Default	Description
connect	5s	Maximum time to accept a client connection
header_read	10s	Maximum time to read request headers
body_read	60s	Maximum time to read the full request body
idle_keepalive	60s	How long to keep idle connections alive
backend_connect	5s	Maximum time to establish a backend connection
backend_first_byte	60s	Maximum time to receive the first byte from backend
backend_between_bytes	30s	Maximum time between bytes from backend

[server.limits]

Resource limits protecting against abuse.

Key	Default	Description
max_connections	10000	Maximum concurrent connections
max_header_size	32 KiB	Maximum total size of all headers
max_body_size	10 MiB	Maximum request body size
max_uri_length	8192	Maximum URI length in bytes
max_headers	100	Maximum number of headers

[[backends]]

One or more backend origin servers. Multiple backends enable load balancing.

Key	Description
name	Identifier for this backend
address	Backend address in host:port format

[cache]

Cache behavior settings.

Key	Default	Description
enabled	true	Enable or disable caching
max_memory	1 GiB	Maximum memory for cached objects
grace_period	60s	Serve stale content for this long after expiry
stale_while_revalidate	true	Serve stale content while refreshing in background

[ttl]

Time-to-live settings for cached objects.

Key	Default	Description
mode	"origin"	"origin" respects Cache-Control headers; "override" ignores them
default	1h	Default TTL when origin doesn't specify one
max	24h	Maximum TTL cap regardless of origin headers

[admin]

Admin API for cache management, purging, banning, and health checks.

Key	Default	Description
enabled	true	Enable or disable the admin API
address	127.0.0.1:6085	Bind address (keep on localhost for security)

[logging]

Key	Default	Description
level	"info"	Log level: trace, debug, info, warn, error
format	"json"	Output format: "json" or "text"

Config File Location

Platform	Path
Linux	/etc/trident/config.toml
FreeBSD	/usr/local/etc/trident/config.toml

Override with the --config flag:

trident --config /path/to/config.toml

Multi-site Configuration

Use include at the top level to split configuration across files:

include = ["sites-enabled/*.toml"]

This loads all .toml files from the sites-enabled/ directory relative to the main config file.