Configuration#

Location#

The config file is loaded from one of two places:

The path set in the ONIS_CONFIG environment variable
onis.toml in the current working directory (default)

If the file does not exist, all options fall back to their defaults. Every field is optional. A default config is provided here, with the default values that are used.

Options#

`[appview]`#

Key	Type	Default	Description
`bind`	string	`"0.0.0.0:3000"`	Address and port for the appview HTTP server
`tap_url`	string	`"ws://localhost:2480/channel"`	WebSocket URL for TAP
`tap_acks`	bool	`true`	Whether to acknowledge TAP messages
`tap_reconnect_delay`	u64	`5`	Seconds to wait before reconnecting after a TAP connection error
`index_path`	string	`"./data/index.db"`	Path to the shared zone index SQLite database
`db_dir`	string	`"./data/dbs"`	Directory for per-DID SQLite databases

`[appview.database]`#

Key	Type	Default	Description
`busy_timeout`	u64	`5`	Seconds to wait when the database is locked
`user_max_connections`	u32	`5`	Max connections for per-user database pools
`index_max_connections`	u32	`10`	Max connections for the shared index database pool

`[dns]`#

Key	Type	Default	Description
`appview_url`	string	`"http://localhost:3000"`	URL of the appview API
`bind`	string	`"0.0.0.0"`	Address for the DNS server to listen on
`port`	u16	`5353`	Port for the DNS server
`tcp_timeout`	u64	`30`	Seconds before a TCP connection times out
`ttl_floor`	u32	`60`	Minimum TTL enforced on all DNS responses
`slow_query_threshold_ms`	u64	`50`	Log a warning for queries slower than this (milliseconds)
`ns`	list[string]	`["ns1.example.com.", "ns2.example.com."]`	NS records served for all zones (fully qualified, trailing dot)
`metrics_bind`	string	`"0.0.0.0:9100"`	Bind address for the metrics HTTP server

`[dns.soa]`#

Default SOA record values for zones without a user-published SOA. These fields are defined in RFC 1035 Section 3.3.13 and are primarily relevant for nameserver maintenance operations between primary and secondary servers.

Key	Type	Default	Description
`ttl`	u32	`3600`	SOA record TTL in seconds
`refresh`	i32	`3600`	SOA refresh interval in seconds
`retry`	i32	`900`	SOA retry interval in seconds
`expire`	i32	`604800`	SOA expire interval in seconds
`minimum`	u32	`300`	SOA minimum (negative cache) TTL in seconds
`mname`	string	`"ns1.example.com."`	Primary nameserver (fully qualified)
`rname`	string	`"admin.example.com."`	Admin email in DNS format (fully qualified)

Field details:

refresh -- The interval at which secondary nameservers should poll the primary to check if the zone's serial number has incremented.
retry -- If a secondary fails to reach the primary during a refresh attempt, it retries after this many seconds.
expire -- If a secondary cannot reach the primary for this long, it stops serving the zone entirely and returns SERVFAIL. This is the upper bound on how long stale data can be served.
minimum -- Originally defined in RFC 1035 as a lower bound on TTL for all RRs in the zone (resolvers would set TTL to the maximum of the record's own TTL and this value). RFC 2308 redefined this field to mean the negative caching TTL -- how long resolvers should cache NXDOMAIN and NODATA responses.
mname -- The FQDN of the primary nameserver for the zone. Must include the trailing dot.
rname -- The email address of the zone administrator, encoded in DNS format: the @ is replaced with a ., so admin@example.com becomes admin.example.com.. Must include the trailing dot. This is informational and not used by resolvers programmatically, but it is exposed in SOA query responses.

`[verify]`#

Key	Type	Default	Description
`appview_url`	string	`"http://localhost:3000"`	URL of the appview API
`bind`	string	`"0.0.0.0"`	Address for the verify API server
`port`	u16	`3001`	Port for the verify API server
`check_interval`	u64	`60`	Seconds between scheduled verification runs
`recheck_interval`	i64	`3600`	Seconds a zone must be stale before reverification
`expected_ns`	list[string]	`["ns1.example.com", "ns2.example.com"]`	Expected NS records that indicate correct delegation (should match `dns.ns`)
`nameservers`	list[string]	`[]`	Custom resolver IP addresses (optional, uses system resolvers if empty)
`dns_port`	u16	`53`	Port used when resolving against custom nameservers

Example config#

A full onis.toml with all defaults:

[appview]
bind = "0.0.0.0:3000"
tap_url = "ws://localhost:2480/channel"
tap_acks = true
tap_reconnect_delay = 5
index_path = "./data/index.db"
db_dir = "./data/dbs"

[appview.database]
busy_timeout = 5
user_max_connections = 5
index_max_connections = 10

[dns]
appview_url = "http://localhost:3000"
bind = "0.0.0.0"
port = 5353
tcp_timeout = 30
ttl_floor = 60
slow_query_threshold_ms = 50
ns = ["ns1.example.com.", "ns2.example.com."]
metrics_bind = "0.0.0.0:9100"

[dns.soa]
ttl = 3600
refresh = 3600
retry = 900
expire = 604800
minimum = 300
mname = "ns1.example.com."
rname = "admin.example.com."

[verify]
appview_url = "http://localhost:3000"
bind = "0.0.0.0"
port = 3001
check_interval = 60
recheck_interval = 3600
expected_ns = ["ns1.example.com", "ns2.example.com"]
nameservers = []
dns_port = 53

Configuration#

Location#

Options#

[appview]#

[appview.database]#

[dns]#