Configuration reference

goethite reads one TOML file, given with --config. Every setting has a default, except that a resolver is required: at least one [[upstream]], or [recursion] enabled = true. Unknown keys are errors, so a typo never silently falls back to a default. Run goethite check-config --config <path> to check a file. The commented example config is a good starting point.

The file is read at startup. SIGHUP (systemctl reload goethite) re-reads the filter lists and the TLS certificates but not the file itself; restart goethite after changing it. Files over 1 MiB are refused.

The development default port, 15353, needs no root. Port 5353 is avoided because multicast DNS uses it.

Queries per client network, over UDP, TCP, DNS over TLS, HTTPS and QUIC together; see rate limiting. Which clients may use goethite at all is not set here but in the replicated settings (access control).

Loopback clients are never limited.

DNS over TLS, HTTPS and QUIC for clients; see Encrypted DNS. Without this table, none is served.

At least one of dot, doh and doq is required. No TCP address may be used twice across [server], [server.tls], [api] and [cluster], nor a UDP address across [server] listen and doq. Encrypted connections, QUIC ones included, count against max_tcp_connections and max_tcp_connections_per_client.

The resolvers goethite forwards to, tried in the order they appear, with failover. At least one is required, unless [recursion] is enabled instead, and at most 16 are allowed. An upstream that fails three times in a row is skipped for 30 seconds.

Certificates are checked against the Mozilla root certificates built into goethite, not the operating system's store. Each query has 2 seconds per upstream and 4 seconds in total. Queries to tls and https upstreams are padded so their size says less about the name.

Resolve every name from the root servers down instead of asking [[upstream]] resolvers; see Recursion. A config file has one or the other.

See Filtering for the rule syntax.

Filtering configuration lives in goethite's store, where the API changes it. This table seeds the store on the first start and is then only read by goethite import: the store is the source of truth, so if the table changes later, goethite logs a warning and keeps what the store says. To apply the table again, stop goethite and run goethite import --config <file>, which replaces the lists and rules that came from the config file and keeps those created through the API.

Up to 63 lists, each with exactly one of:

Lists may be at most 128 MiB.

The state directory is systemd's StateDirectory (/var/lib/goethite with the shipped unit) or, without it, the config file's directory. The file is created readable by goethite's user only, and only one goethite process can open it at a time.

See REST API for how to use it.

Absent for a node on its own. With it, the node is a member of a cluster whose members agree on the filtering configuration with Raft. goethite witness reads the same table. See High availability.

One table for each other member, up to 15. Only members in a member's config file, or already in the cluster, may connect to it. The leader adds the members in its config file as they answer.

goethite 0.4's [cluster.peer] table, with the same keys, still counts as one member.

Absent unless the node shares a floating IP with another: the address that whichever node is healthy holds, moved by goethite vrrp. See High availability.

Each entry records when, the client's address (and its known client and group), the protocol, the name and type asked for, the response code, how the answer came about (cached, forwarded and from which upstream, blocked and by which rule and list, and so on) and how long it took. A busy home network logs tens of thousands of queries a day, which takes a few megabytes. Hourly statistics, with the 100 names, blocked names and clients seen most each hour, are kept for 30 days.

Logging never slows answers down: queries are queued, and if the writer falls behind, entries are dropped and counted (goethite_querylog_dropped_total in the metrics) rather than delaying anyone.

Sends goethite's metrics, log records and, if turned on, traces to an OpenTelemetry collector over OTLP/HTTP, as well as serving the metrics at /metrics and writing the log to standard error. Nothing is sent without endpoint. See Metrics and telemetry.

goethite resolves the collector's name through its own upstreams and local records, not the system's resolver: use an address, or a name those answer. headers_file and ca_file are read before goethite drops its privileges, so they may be readable by root only. Over plain HTTP beyond loopback, goethite warns that the metrics and the headers can be read on the way.

Logs go to standard error, and the RUST_LOG environment variable sets the level (default info). For example, RUST_LOG=debug shows dropped and rejected packets, and RUST_LOG=goethite_resolver=debug shows only the resolver's details. Two libraries say less unless RUST_LOG names them, since goethite reports what they would itself: hickory-proto, which would quote malformed packets, is off, and openraft, which logs every election and membership change, logs warnings only (RUST_LOG=info,openraft=info shows them).