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

JSON

{
  "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:

Bash

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

Multi-site Configuration

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

JSON

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

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