Configuration

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

Default Configuration

{
  "server": {
    "listeners": [
      { "address": "0.0.0.0:8120" }
    ],
    "timeouts": {
      "connect": "5s",
      "header_read": "10s",
      "body_read": "60s",
      "idle_keepalive": "60s",
      "backend_connect": "5s",
      "backend_first_byte": "60s",
      "backend_between_bytes": "30s"
    },
    "limits": {
      "max_connections": 10000,
      "max_header_size": "32 KiB",
      "max_body_size": "10 MiB",
      "max_uri_length": 8192,
      "max_header_count": 100
    }
  },
  "backends": [
    {
      "name": "origin",
      "host": "127.0.0.1",
      "port": 8080
    }
  ],
  "cache": {
    "enabled": true,
    "max_memory": "1 GiB",
    "grace_period": "60s",
    "stale_while_revalidate": true
  },
  "ttl": {
    "mode": "origin",
    "default": "1h",
    "max": "24h"
  },
  "admin": {
    "enabled": true,
    "address": "127.0.0.1:6085"
  },
  "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_header_count	100	Maximum number of headers

[[backends]]

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

Key	Description
name	Identifier for this backend
host	Backend hostname or IP address
port	Backend port number

[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.json
FreeBSD	/usr/local/etc/trident/config.json

Override with the --config flag:

trident --config /path/to/config.json

Multi-site Configuration

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

{
  "include": ["sites-enabled/*.json"]
}

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