Glossary
This glossary gives brief definitions of terminology used in this documentation. Each entry links to the canonical topic page for detail.
When writing other pages, link here often — for example [overlay](/glossary/index.md#overlay) or [Rhai](/rhai/index.md).
Entries are added as documentation grows. Keep one-line glosses in sync when linked pages change.
Config model
Overlay
In-memory config patch applied with conduitctl apply; merge mode accumulates successive patches, then combines with the file layer into effective config. Cleared by reload from disk, conduitctl apply --clear, or conduitctl apply --replace with an empty patch (schema_version only).
Clear overlay (without reload)
conduitctl apply --clear: drop the active overlay without re-reading the file layer from disk — distinct from reload from disk, which re-reads the startup file and clears the overlay.
File layer
YAML read from the path passed at conduit startup — the durable baseline on disk, distinct from any API overlay.
Effective config
File layer after merge with the active overlay (if any) and before compile into a runtime snapshot.
Export
YAML serialization of the effective config (file layer plus active overlay, defaults normalized) via conduitctl export or gRPC ExportConfig.
Reload from disk
SIGHUP or conduitctl reload: re-read the startup config file from disk, clear the overlay, validate, and swap the runtime snapshot. Afterward, effective config comes from the on-disk file only.
Runtime
Runtime snapshot
The validated configuration settings bundle the dataplane uses to answer queries at a given moment — effective config (listeners, pools, forward behavior, health probe settings), loaded rules and scripts, and observability filters. All listener workers share the same snapshot until you reload or apply new settings. Backend health runtime state (observed/applied liveness, freeze/drain) lives outside the snapshot.
→ Architecture and packet path, Configuration model
Last-good snapshot
The previous working runtime snapshot Conduit keeps when a reload or apply fails validation — DNS continues on the last known-good settings instead of the rejected change.
Pending reconcile
Snapshot updated after a reload or apply, but listeners or forward socket state still reflects the previous process start — restart conduit to apply on the wire.
Runtime model
The dataplane execution model chosen once at process startup with dataplane.runtime — sync (default) or split_io — deciding how the per-query defined pipeline is spread across OS threads. It does not change the pipeline phases; changing it (or its worker counts) requires a restart.
Ingress worker
OS thread that accepts a client DNS message on a listener (count from listeners.threads). Under sync it runs the whole pipeline including the upstream wait; under split_io it does the structural parse, takes a transaction slot, and hands off without blocking on upstream.
Policy worker
Under split_io, a thread (count from dataplane.policy_workers) that runs the orchestrator phases — Request rules, Lookup (including forward provider submit), and finishes each transaction at Response rules / Send once a reply is in.
I/O worker
Under split_io, a poll thread (count from dataplane.io_workers) that owns a set of upstream egress sockets: it matches incoming replies to parked transactions, enforces forward.timeout_ms, and resumes each transaction at Wait for response. io_workers: N starts N such threads; each handles many concurrent parked waits on its own sockets.
Transaction slot pool
Preallocated arena of transaction slots, shared by both runtime models, that grows in chunks (dataplane.slot_chunk_size) up to orchestrator.txn_table_capacity. A query holds one slot from Receive to Send — including while a split_io query is parked waiting upstream. When all slots are in use Conduit applies backpressure and increments conduit_slot_pool_exhausted_total.
Datapath
Lookup (pipeline phase)
Top-level pipeline phase after Request rules where Conduit runs ordered lookup providers (cache, forward) to produce the wire answer. Distinct from Rhai lookup(table, key) — see Lookup vs lookup(table, key).
→ Architecture and packet path — Lookup
Lookup vs lookup(table, key)
| Name | What it is |
|---|---|
| Lookup (phase) | Pipeline step — cache and forward providers produce DNS answers |
lookup(table, key) |
Rhai function — reads a data_sources: policy table by key; returns a string or "" on miss |
→ Lookups, Data sources, Architecture — Lookup
Answer source
How the lookup spine produced the client answer: cache or forward. Exposed on built-in response metrics (answer_source label), event export selectors, and txn.answer_source() on the response hook.
→ Built-in metrics — conduit_responses_total, Transaction API — Answer provenance
0x20 encoding
Mixed-case QNAME bit encoding some recursive clients use as an anti-spoofing check: they expect the response Question to echo the same letter casing they sent. Cache hits rewrite the Question (and EDNS) from the current client query so those clients accept cached answers.
→ DNS answer cache — Serve rewriting
Dataplane
The conduit service and query-processing runtime: configured listeners accept client DNS traffic, each query runs through the pipeline as a transaction, and responses come from upstream backends. Distinct from the optional control plane, which exposes gRPC and conduitctl when enabled.
→ Architecture and packet path
Listener
A configured client-facing DNS bind address (listeners.listeners[]: address + protocol udp or tcp). Distinct from the optional gRPC control: listener.
Transaction
Everything Conduit remembers for one client query on the dataplane — the question, client and listener context, tags, selected pool and backend, query and response messages, and optional trace — from Receive through Send or drop.
→ Architecture and packet path
Tags
Runtime key/value annotations on a transaction, set or tested by rules and scripts; persist across retries unless cleared. Not part of on-disk config export.
→ Architecture and packet path
Retry
Another Lookup cycle for the same client transaction, triggered from Response rules via the retry or retry_now action (or Rhai); capped by orchestrator.max_attempts, orchestrator.max_txn_duration_ms, and pool exhaustion when every backend in the target pool was already tried.
Pool
Named group of backends; rules and scripts select a pool by name before Conduit picks a backend to forward to.
Backend
Configured upstream destination Conduit forwards DNS queries to; settings control how Conduit reaches and uses that destination (for example address and weight).
Observed health
Probe- and passive-derived liveness for a backend — always updated as probes and live forwards run. Route does not read observed health directly; use applied health for eligibility.
→ Backend health — Observed vs applied
Applied health
The liveness value Route uses to decide whether a backend is eligible. Normally tracks observed health; holds steady when the backend is frozen or drained.
→ Backend health, Built-in metrics — conduit_backend_health_applied
Freeze
Operator or scope state that stops probe-driven changes to applied health while observed health keeps updating. Applied stays at its current value (up or down); freeze alone does not take traffic off a backend. Used for incident holds and as part of a drain.
→ Backend health — Operator controls, conduitctl health freeze
Drain
Operator action that takes a backend out of rotation for maintenance: sets applied health to down and freezes that scope so probes cannot put it back. Implemented as conduitctl health set down. Not the same as graceful drain on shutdown.
→ Backend health — Operator controls, conduitctl health set down
Passive fast-trip
Live forward timeouts and hard errors on client traffic that can mark a backend down faster than active probes alone; cannot mark a backend up again (only rise consecutive successful probes do).
→ Backend health — Active probes and passive fast-trip
Fail-open floor
Configured min_eligible threshold: when too few backends in a pool are eligible, Route ignores health and treats all backends as eligible rather than failing the pool. Single-backend pools always fail open.
→ Backend health — Route, Reference: health — min_eligible
EWMA
Exponentially weighted moving average — a smoothed statistic that blends each new measurement with prior history, giving more weight to recent samples than to older ones. Conduit updates a per-backend latency EWMA from successful health-probe round-trip times. That value reflects how fast the backend has been responding lately (not a single spike or one slow query). Route uses the EWMA — through a damped weight_factor — to reduce traffic share to slower but still-eligible backends without removing them from the pool.
→ Runtime API — latency_ewma_ms, min_latency_ewma_ms, Backend health
Rule
Named policy entry under rules: with a hook (request or response), selectors, and an ordered list of actions. Conduit evaluates rules in first-match order on each hook; when a rule matches, its actions run top to bottom.
Selector
Condition on a rule that tests query or response fields (for example query name, type, response code, or tag presence). Conduit evaluates rules in first-match order on each hook.
RCODE
DNS response code for the current forward attempt (for example SERVFAIL, NOERROR). Response rules match on rcode selectors; Rule Rhai uses txn.response_rcode() on the response hook.
→ Rules and actions — Selectors, Transaction API — Query and response
sample_percent
Deterministic sampling on a 0..100 scale. 0 never matches; 100 always matches. By default the hash uses the transaction id only. Optional key (static string) or key_from (qname, rule_name on rules, sink_name on event sinks) selects an independent bucket namespace — see Sampling and cadence.
On rules, use selector type sample_percent with optional key / key_from, or every_nth_worker / every_nth_global. On tracing and event export, use top-level sample_percent with optional sample_key / sample_key_from. Rhai: txn.sample_percent and related methods on Transaction API — Sampling.
→ Sampling and cadence, Event export, Tracing
every_nth selectors
Rule selectors that match every Nth query: every_nth_worker uses the worker-local transaction id; every_nth_global uses a process-wide query index incremented once per query. Rules only — not valid on tracing or event filter selectors.
Action
Built-in effect on a matching rule (for example set_pool, set_retry_pool, set_tag, set_source_v4, set_source_v6, set_retry_source_v4, set_retry_source_v6, clear_retry_source_v4, clear_retry_source_v6, drop, drop_now, clear_drop, retry, retry_now, clear_retry, clear_retry_pool, rhai) — run in list order on the matching rule.
Rule Rhai
Also called: Rhai for rules.
Scripted policy on rules: .rhai files referenced from rhai actions, loaded into the runtime snapshot on reload or apply, run at Request rules and Response rules within sandbox limits. Uses the txn API — not DNS wire editing.
→ Rule Rhai, Rhai, Rules and actions
Rhai
Embedded scripting in Conduit — Rule Rhai on rules: for policy on the request and response hooks.
→ Rhai
Control and operations
Control plane
Optional gRPC API and operator tools (conduitctl, reload, export). Separate from the DNS dataplane, which serves queries whether or not control is enabled.
conduitctl
CLI for the control plane — apply (with merge / replace / clear modes), export, reload, validate, trace, and health.
Observability
Event sink
Configured destination (for example a dnstap collector) that receives per-query observation frames from the dataplane.
dnstap
Industry-standard protobuf format and framestream transport for DNS observation; Conduit exports client query/response (and optional retry) frames when events.sinks includes type: dnstap.
Pipeline trace
In-memory record of pipeline phases, timing, and routing decisions for one transaction; fetched via GetTrace / conduitctl trace when tracing is enabled.
→ Tracing