Meta tags:
description=Fast, ultra-customizeable, pluggable DNS server (forwarding, recursive, or none) with caching, filtering, routing, DNSSEC, admin UI, and plugins. UDP/TCP/DoT/DoH. - zallison/foghorn;

Headings (most frequently used words):

and, dns, filter, over, example, uh, oh, foghorn, documentation, navigation, files, config, plugins, query, listener, tls, upstream, domain, code, saved, searches, configuration, use, your, server, quick, overview, upstreams, variables, footer, dot, keys, block, stats, log, doh, with, docker, hosts, adblock, flaky, mdns, hardening, protection, rate, file, prefetch, new, finger, lan, ad, search, repositories, users, issues, pull, requests, provide, feedback, zallison, operations, full, menu, to, results, more, quickly, folders, latest, commit, history, repository, table, of, contents, additonal, thanks, start, install, additional, layout, listeners, by, plugin, cookbook, sample, configurations, stargazers, time, about, releases, packages, contributors, languages, pipeline, highly, customizable, fits, into, infrastructure, minimal, headless, installs, optional, dependencies, makefile, helpers, rendering, diagrams, graphviz, top, level, logging, udp, tcp, https, behind, an, http, reverse, proxy, helper, make, targets, for, certificates, access, control, acl, containers, list, downloader, lists, simulator, bonjour, bridge, security, amplification, limiting, per, routing, router, 10, inline, based, records, zone, 11, rebinding, dns_rebinding, rewrites, examples, greylist, names, greylist_example, whois, new_domain, file_over_dns, basic, usage, named, subnets, kids, vs, adults, why, local, workstation, home, kid, smb, small, business, enterprise, layered, caches, rich, topics, resources, license, contributing, stars, watchers, forks, glibc, trust, the, dnssec, bit, flood, no, changes,

Text of the page (most frequently used words):
and (143), the (141), config (104), dns (100), for (81), plugins (67), true (64), #foghorn (59), server (54), example (53), logging (49), with (46), type (46), you (44), host (40), plugin (38), port (36), enabled (35), udp (34), dot (32), filter (32), docker (31), make (31), query (30), tls (29), zone (28), from (27), lan (27), doh (26), tcp (26), upstreams (26), targets (26), cache (26), records (26), are (25), when (25), can (24), that (24), listen (24), log (24), backend (23), per (23), your (23), dnssec (22), var (22), false (22), over (21), domain (21), hosts (21), python (20), stats (20), ttl (20), run (20), 192 (20), 168 (20), local (20), files (20), resolver (19), listener (19), admin (18), default (18), optional (18), upstream (18), file (18), list (18), rate (17), all (17), code (17), backends (16), txt (16), this (15), github (15), mdns (15), level (15), transport (15), name (15), security (14), allow (14), endpoints (14), deny (14), key (14), use (14), via (14), https (14), yaml (14), hooks (13), only (13), http (13), memory (13), com (13), build (13), configuration (13), pre_resolve (12), pre_priority (12), internal (12), client (12), variables (12), using (12), suffix (11), corp (11), vars (11), first (11), 300 (11), kids (11), block (11), environment (11), keys (11), ecs (11), not (10), proxy (10), into (10), lists (10), file_paths (10), enterprise (10), user (10), sqlite (10), module (10), configured (10), overrides (10), these (10), names (10), same (10), finger (10), view (10), new (10), controls (10), set (10), string (10), reload (9), recursive (9), none (9), async (9), strategy (9), redis (9), etc (9), failover (9), dev (9), style (9), based (9), more (9), trust (9), error (8), adblock (8), router (8), priority (8), org (8), 853 (8), multiple (8), mode (8), db_path (8), keep (8), specific (8), them (8), aaaa (8), resolve (8), helpers (8), other (7), here (7), url (7), info (7), server_name (7), verify (7), profile (7), statistics (7), mariadb (7), limiting (7), small (7), ips (7), some (7), validation (7), values (7), one (7), order (7), helper (7), answers (7), add (7), source (7), zonerecords (7), nxdomain (7), each (7), rfc (7), also (7), response (7), setup (7), signed (7), makefile (7), cachetools (7), ttlcache (7), commit (7), readme (6), greylist (6), need (6), global (6), zones (6), office (6), acl (6), round_robin (6), refused (6), control (6), query_log_only (6), simple (6), domains (6), forward (6), how (6), load (6), like (6), they (6), different (6), such (6), queries (6), start (6), before (6), examples (6), prefetch (6), behaviour (6), post_resolve (6), post (6), merge (6), inline (6), bind_paths (6), any (6), entry (6), create (6), size (6), hardening (6), development (6), certificate (6), pem (6), ssl (6), listeners (6), without (6), settings (6), documentation (6), sign (6), install (6), zallison (6), support (6), community (5), navigation (5), there (5), while (5), page (5), contributing (5), license (5), developer (5), forwarding (5), match (5), caches (5), source_backend (5), crt (5), auto (5), mysql (5), which (5), instance (5), 127 (5), schema (5), will (5), runtime (5), single (5), override (5), data (5), top (5), containers (5), path (5), window (5), protection (5), but (5), under (5), address (5), soa (5), qtype (5), authoritative (5), both (5), notes (5), ixfr (5), full (5), axfr (5), servfail (5), limits (5), built (5), flaky (5), additional (5), short (5), quick (5), reverse (5), want (5), options (5), changes (5), features (5), search (5), action (4), docs (4), was (4), loading (4), please (4), packages (4), latest (4), test (4), caching (4), routing (4), shape (4), max_connections (4), mongodb (4), targeting (4), goals (4), deny_response (4), window_seconds (4), smb (4), printer (4), driver (4), myisp (4), persistence (4), access (4), persistent (4), business (4), 100 (4), just (4), ads (4), home (4), kid (4), errors (4), section (4), out (4), main (4), normal (4), keeps (4), then (4), supports (4), avoid (4), environments (4), whois (4), most (4), read (4), own (4), uses (4), unless (4), exact (4), replace (4), max (4), through (4), inside (4), including (4), custom (4), note (4), connection (4), enabling (4), see (4), includes (4), bonjour (4), services (4), subnet (4), their (4), available (4), cname (4), requests (4), random (4), debug (4), legacy (4), startup (4), abort_on_failure (4), logs (4), alias (4), query_log_sampling (4), events (4), writes (4), mqtt (4), ede (4), glibc (4), sshfp (4), another (4), ssh (4), function (4), maxsize (4), diagram (4), bundle (4), dependencies (4), env (4), pull (4), thanks (4), pipeline (4), actions (4), quality (4), issues (4), time (3), information (3), manage (3), html (3), releases (3), repository (3), stars (3), resources (3), topics (3), fast (3), filtering (3), blocked_domains_files (3), routes (3), remote (3), 120 (3), unix (3), sock (3), api (3), influx (3), database (3), pool (3), max_concurrent (3), dns_cache (3), memcached (3), key_file (3), cert_file (3), fine (3), heavy (3), per_client (3), floor2 (3), floor1 (3), bridge (3), deny_response_ip4 (3), blocklists (3), interfaces (3), cloudflare (3), yet (3), public (3), configurations (3), json (3), raw (3), may (3), even (3), container (3), few (3), line (3), define (3), subnets (3), strict (3), rules (3), common (3), easy (3), syntax (3), usage (3), later (3), sources (3), last (3), base64 (3), format (3), file_over_dns (3), end (3), new_domain (3), blocks (3), greylist_example (3), allowed (3), origin (3), responses (3), rewrites (3), qtypes (3), treat (3), whether (3), prefer (3), creating (3), directly (3), advanced (3), users (3), running (3), types (3), dns_rebinding (3), non (3), rebinding (3), bind (3), pipe (3), delimited (3), enable (3), record (3), value (3), max_records (3), bytes (3), returns (3), apex (3), have (3), containing (3), either (3), object (3), entire (3), protections (3), exposed (3), amplification (3), below (3), unbounded (3), limit (3), depth (3), net (3), expose (3), testing (3), remove (3), discovery (3), cert (3), ca_file (3), foghorn_ca (3), generate (3), behind (3), opcodes (3), defaults (3), secure (3), sample_rate (3), skipped (3), integration (3), example_configs (3), rows (3), compatibility (3), skip (3), every (3), cap (3), include (3), upstream_host (3), servers (3), web (3), inbound (3), edns (3), behavior (3), bit (3), lru_cache (3), rr_cache (3), lfu_cache (3), func_caches (3), let (3), tune (3), sent (3), chain (3), overview (3), openssl (3), publish (3), package (3), images (3), venv (3), assets (3), date (3), require (3), missing (3), models (3), tests (3), src (3), pre (3), its (3), operations (3), changelog (3), workflows (3), open (3), insights (3), tab (3), refresh (3), session (3), saved (3), feedback (3), grade (3), copilot (3), platform (3), solutions (3), explore (3), share (2), status (2), footer (2), 2026 (2), forks (2), mit (2), active (2), network (2), ultra (2), customizeable (2), pluggable (2), about (2), mix (2), service (2), office_remote (2), devices (2), pg_primary (2), metrics (2), write (2), foghorn_stats (2), postgres (2), grained (2), postgresql (2), plus (2), large (2), edge (2), layered (2), rich (2), min_enforce_rps (2), floor2_net (2), printers (2), floor1_net (2), used (2), dot2 (2), dot1 (2), library (2), homework (2), allowed_domains (2), urls (2), interval_days (2), download_path (2), route (2), allowlist (2), workstation (2), show (2), adjust (2), paths (2), sample (2), ides (2), case (2), setups (2), prod (2), flags (2), might (2), command (2), safer (2), secrets (2), shared (2), once (2), reuse (2), less (2), repetition (2), why (2), adults (2), named (2), test_subnet (2), main_subnet (2), reference (2), variable (2), system (2), configs (2), exposes (2), reading (2), template (2), pattern (2), rest (2), appear (2), apply_to_qtypes (2), interval_seconds (2), very (2), cases (2), than (2), production (2), intended (2), work (2), live (2), 172 (2), allowlisted (2), private (2), overwrite (2), merge_policy (2), load_mode (2), zonefiles (2), generated (2), ptr (2), accepted (2), where (2), nodata (2), rrset (2), defines (2), rebuilds (2), existing (2), counts (2), treats (2), matching (2), side (2), behaves (2), dropped (2), pair (2), explicit (2), rejected (2), 1035 (2), dnslib (2), noerror_empty (2), traffic (2), sizes (2), payloads (2), provides (2), combined (2), method (2), healthy (2), entries (2), prevent (2), growth (2), health (2), configurable (2), recursion (2), max_depth (2), zeroconf (2), must (2), timeouts (2), simulator (2), entirely (2), maps (2), 203 (2), 113 (2), answer (2), synthesize (2), applies (2), flexible (2), safe (2), allowlists (2), downloader (2), null (2), serve (2), minimal (2), cookbook (2), lab (2), needs (2), foghorn_ (2), myserver (2), self (2), convenience (2), certificates (2), 8443 (2), itself (2), plain (2), forwards (2), 8053 (2), off (2), accept (2), rcodes (2), noerror (2), domains_mode (2), ignore_ips (2), knobs (2), lets (2), direct (2), logger (2), aliases (2), cidr (2), preferred (2), wide (2), stderr (2), syslog (2), runs (2), retention_vacuum_interval_seconds (2), retention_vacuum_on_prune (2), enables (2), retention_days (2), query_log_dedupe (2), prune_every_n_inserts (2), prune_interval_seconds (2), max_bytes (2), days (2), query_log_retention (2), max_logging_queue (2), until (2), episode (2), down (2), guide (2), suppress (2), queue (2), bounded (2), explicitly (2), insert (2), recommended (2), flood (2), ignore (2), batch_writes (2), master (2), switch (2), selects (2), request (2), handling (2), topic (2), describes (2), get (2), forward_local (2), enable_ede (2), selection (2), trusted (2), outbound (2), 8914 (2), extended (2), flag (2), applications (2), tools (2), systems (2), decorated (2), table (2), fifo_cache (2), registered_cached (2), clear (2), foghorn_ttl (2), sqlite_ttl (2), registered_sqlite_ttl (2), foghornttlcache (2), registered_foghorn_ttl (2), positive (2), immediately (2), circuits (2), flows (2), layout (2), compliance (2), png (2), ship (2), clean (2), writing (2), javascript (2), dist (2), cdn (2), 5380 (2), prebuilt (2), amd64 (2), armhf (2), hub (2), image (2), installed (2), git (2), clone (2), pip (2), track (2), ssh_keys (2), import (2), exit (2), fastapi (2), dnspython (2), etchosts (2), developers (2), good (2), wire (2), teams (2), hole (2), integrates (2), influxdb (2), sql (2), databases (2), customizable (2), forwarder (2), seamlessly (2), pyproject (2), toml (2), entrypoint (2), compose (2), dockerfile (2), description (2), gitignore (2), scripts (2), 945 (2), commits (2), message (2), menu (2), projects (2), appearance (2), cancel (2), searches (2), repositories (2), customer (2), devops (2), app (2), perform, personal, cookies, contact, privacy, terms, inc, languages, contributors, jun, report, watching, watchers, activity, badge, resolvers, pihole, adblocker, networking, stargazers, exactly, global_block, infra, bucket, write_url, 8086, foghorn_ro, 5432, reporting, pg_reporting, postgr, idle_timeout_ms, 30000, namespace, 6379, priorities, deployments, thing, mycorp, driver_fallback, connector, 3306, everyone, stats_lan, separate, second, stricter, 5353, locally, speed, sketches, pieces, fit, together, editors, interpolate, placeholders, spurious, though, correctly, caveat, base, staging, redefine, dsn, addresses, rely, tokens, passwords, sensitive, passing, hostnames, throughout, place, update, elsewhere, basic, earlier, ones, resolved, highest, committed, adapt, sites, max_chunk_bytes, 1024, file_path, serves, byte, ranges, whois_cache_ttl_seconds, 3600, whois_db_path, whois_cache, threshold_days, too, according, duration_hours, cache_ttl_seconds, introduces, delay, project, started, researchers, working, phishing, max_subdomains, base_labels, playground, rewrite, demonstrate, behaviours, max_consecutive_misses, prefetch_top_n, prefetches, popular, warm, efficient, shows, concept, starting, points, decide, trade, offs, rather, dropping, functional, implementations, wired, references, move, copy, corresponding, filters, shipped, now, lookup, fe80, fc00, 128, 169, 254, private_cidrs, allowlist_domains, allowlist_mode, queried, resolves, space, 2001, db8, native, inferred, fallback, exists, soa_synthesis_enabled, bound, max_auto_ptr_records, auto_ptr_enabled, length, characters, max_record_value_length, cycle, max_file_size_bytes, suffixes, does, exist, instead, falling, resolution, nxdomain_zones, appends, distinct, replaces, group, axfr_zones, ignores, others, mapping, preserves, overlays, benchmarked, higher, 000, operational, guidance, leading, label, labels, differs, 4592, matches, wildcard, supported, currently, implemented, transfer, marks, correct, semantics, authority, kept, seen, duplicates, comes, occurrence, across, merged, restrict, directory, prefixes, segments, path_allowlist, parsed, above, handful, maintain, zonefile, send, dbs, rate_limit, stats_log_interval_seconds, 900, burst_windows, burst_factor, warmup_windows, per_client_domain, per_domain, adaptive, inflight, shedding, trigger, evaluates, deploying, consider, monitoring, patterns, rates, capped, 1232, minimize, potential, limited, caps, defense, layers, max_queries_per_connection, max_connections_per_ip, concurrency, periodically, removes, stale, tracking, dictionary, upstream_health, dnsudphandler, _cleanup_upstream_health, cleanup, abuse, deep, delegation, chains, oversized, encoded, parameters, 413, decoding, preventing, processing, megabyte, scale, parameter, several, mitigate, dos, ddos, attacks, risks, network_enabled, include_ipv6, include_ipv4, avahi, receive, macvlan, noerror_empty_percent, truncate_percent, timeout_percent, nxdomain_percent, servfail_percent, injects, current, game, obession, cheat, blocked_domains, 198, strip, replace_with, landing, blocked_ips, inspection, happens, pointing, sinkhole, overridden, adblockers, serverb, servera, easily, handled, hashing, hash_filenames, early, fetches, schedule, stores, watchdog_enabled, 2375, descriptions, assume, pki, management, acting, export, anchor, material, 443, terminated, nginx, envoy, typically, terminate, localhost, handles, termination, decides, chosen, talk, turn, never, typical, stanza, bump, output, differently, treated, form, codes, restriction, insecure, unsecure, exclude, target, nested, actual, failing, aborts, hook, stable, identifier, surfaced, normally, care, plugininstance, retention_optimize_interval_seconds, retention_optimize_on_prune, index, retention_native_ttl, incremental, sqlite_auto_vacuum, maintenance, retention_prune_every_n_inserts, retention_prune_interval_seconds, retention_max_bytes, 1073741824, retention_max_records, 250000, max_entries, 50000, 200, 2147483648, 500000, 4096, remaining, cools, plugindecision, suppress_query_log, denies, blocked, deny_log_first_n, detailed, query_log_hardening, repeated, identical, query_log_sample_rate, fraction, collector, mirroring, aggregate, counters, prune, cadence, pruning, estimated, storage, age, row, count, cannot, grow, bounds, top_domains, top_domains_mode, ignore_single_host, don, display, include_in_stats, primary, important, fields, performed, background, worker, stays, setting, forces, synchronous, query_log, 1883, mqtt_logging, backup, written, facility, tag, warn, critical, process, certs, quad9, surface, logged, duplicated, succeeds, again, spam, malformed, txid, question, failed, continues, mismatched, definitions, maximum, simultaneous, outstanding, try, talks, miss, walk, root, still, influences, reads, bypassed, cross, contamination, influence, use_for_plugin_targeting, gates, trusted_client_cidrs, trusted_listeners, synthesize_from_client_ip, forward_inbound, rfc1918, lookups, attach, selected, synthetic, present, canonical, feature, map, clears, handing, openssh, has, validated, nameserver, edns0, linux, validating, honors, clients, trustworthy, point, resolv, conf, payload, field, column, backed, wrapped, between, purely, desired, reset_on_ttl_change, logical, 2048, seconds, _find_zone_apex_cached, dnssec_validate, min_cache_ttl, increase, cached, functions, valid, sqlite3ttlcache, lrucache, fifocache, rrcache, lfucache, registered_lru_cache, decorated_overrides, modify, underlying, capacity, eviction, instantiated, integer, almost_expired, fifo, lfu, lru, eviction_policy, classic, parts, decision, maybe, calls, resolving, conceptually, ordered, wrap, outputs, interpolation, protocol, made, tpng, render, rendering, diagrams, graphviz, req, x509, optionally, artefacts, temporary, bundled, script, served, suite, coverage, embedded, css, regenerate, prepare, virtualenv, extras, needed, layer, adblocking, listens, privileged, architecture, mounted, along, mappings, checkout, sync, hack, branch, editable, raise, importerror, scanning, modules, foghorn_strict_plugin_discovery, deps, extra, during, fail, due, failure, fatal, uvicorn, requires, cryptography, local_extended, validate, however, depend, third, party, those, lightweight, headless, installs, released, version, gives, cli, pypi, ways, depending, junior, warp, who, docstrings, unit, creates, messages, janitorial, tasks, because, lot, help, special, weatherwax, contributions, inspiration, team, low, primitives, implementation, shout, outs, whole, giant, whose, shoulders, stand, pydantic, black, ruff, pytest, fiona, sampling, replacement, contribution, additonal, installation, contents, valkey, fits, infrastructure, differences, resize, configure, workload, precisely, highly, implement, logic, hour, scope, given, preset, bundles, stored, rate_limit_profiles, _profiles, profiles, fuzzing, seedable, purposes, simulating, unreliable, offers, observability, static, dynamic, reduce, risk, dnsrebinding, vpn, upstreamrouter, bind9, arbitrary, combining, download, similar, return, silently, drop, filedownloader, ideal, result, added, responds, execute, produces, final, flow, times, straightforward, box, standard, lifting, nearly, tunable, observable, everything, almost, anything, empowers, monitor, efficiently, extend, functionality, providing, pages, integrated, dashboard, newer, signing, transfers, utilities, class, tool, versatile, designed, flexibility, performance, robust, foundation, modular, transform, powerful, blocker, capabilities, tailored, items, history, folders, tags, branches, star, fork, change, notification, notifications, dismiss, alert, switched, accounts, resetting, focus, qualifiers, our, results, quickly, submit, email, contacted, piece, take, input, seriously, provide, tips, jump, pricing, premium, ons, powered, collections, trending, archive, program, accelerator, maintainer, programs, fund, sponsors, partners, center, forum, skills, ebooks, reports, webinars, stories, software, industries, government, manufacturing, financial, healthcare, industry, devsecops, modernization, nonprofits, startups, medium, enterprises, company, marketplace, blog, stop, leaks, secret, find, fix, vulnerabilities, application, enforce, review, plan, instant, codespaces, automate, workflow, integrate, external, mcp, registry, agents, issue, better, creation, toggle, content,

Text of the page (random words):
g openssl req x509 rendering config diagrams graphviz dot if you have a diagram dot and want to render it to diagram png dot tpng diagram dot o diagram png additional documentation openssl make targets made easy dns rfc compliance and protocol notes including ede and axfr ssh host keys sshfp records and dnssec integration 2 configuration layout overview 2 1 top level keys at the top level the schema defines these keys vars key value variables for interpolation inside the rest of the file server listener dnssec resolver cache and admin http settings upstreams how outbound dns queries are sent logging global logging level and outputs stats runtime statistics and query log persistence plugins the ordered list of plugins that wrap each query conceptually a request flows like this client udp tcp doh listener dns cache memory redis etc optional plugins pre_resolve chain maybe upstream dns calls or recursive resolving plugins post_resolve chain response or deny note when a pre_resolve plugin returns an override decision the generated response is sent immediately and the post_resolve chain is skipped entirely a post_resolve override short circuits any later post_resolve plugins for that query 2 2 server block key parts of server server listen dns udp dns tcp classic dns listeners dns dot dns over tls listener doh dns over https listener server cache module which cache plugin to use config plugin specific cache settings for the in memory dns cache module memory the underlying foghornttlcache supports optional capacity and eviction controls when instantiated from python code maxsize positive integer unbounded when none or non positive and eviction_policy one of none lru lfu fifo random or almost_expired modify decorated_overrides func_caches optional overrides for internal helper caches functions decorated with registered_cached registered_lru_cache registered_foghorn_ttl or registered_sqlite_ttl these let you tune ttl and maxsize for specific helpers without code changes valid backend values for func_caches entries are ttlcache cachetools ttlcache lfu_cache cachetools lfucache rr_cache cachetools rrcache fifo_cache cachetools fifocache lru_cache cachetools lrucache foghorn_ttl foghornttlcache based helpers via registered_foghorn_ttl sqlite_ttl sqlite3ttlcache based helpers via registered_sqlite_ttl example increase the ttl and maxsize for a dnssec helper cached via cachetools ttlcache server cache module memory config min_cache_ttl 60 func_caches module foghorn dnssec dnssec_validate name _find_zone_apex_cached backend ttlcache ttlcache lru_cache foghorn_ttl sqlite_ttl lfu_cache rr_cache ttl 300 seconds applies to ttl style backends maxsize 2048 logical max size for this helper cache reset_on_ttl_change true clear ttlcache once when ttl changes note the backend field here selects the desired cache backend type for that helper matching the backend column in the admin decorated caches table for cachetools backed helpers wrapped with registered_cached foghorn rebuilds the function s cache at startup so you can switch between ttlcache lfu_cache rr_cache fifo_cache and lru_cache purely from configuration server dnssec mode and dnssec validation knobs e g udp payload size glibc trust ad and the dnssec ad bit on linux systems that use glibc applications including ssh when using sshfp records only see the dnssec ad bit when the resolver is explicitly configured to trust it if you run foghorn or another validating resolver that honors the upstream ad bit and want glibc clients to accept that ad as trustworthy point etc resolv conf at foghorn and add trust ad to the options line nameserver 127 0 0 1 options edns0 trust ad without trust ad glibc clears the ad flag before handing answers to applications so tools like openssh will ignore sshfp records even when foghorn has validated them server features canonical feature flag map for resolver behavior includes enable_ede rfc 8914 extended dns errors attach ede options on selected synthetic responses when edns is present forward_local allow forwarding local and rfc1918 ptr lookups ecs enabled enable edns client subnet handling ecs forward_inbound forward inbound ecs only when it is trusted ecs synthesize_from_client_ip synthesize outbound ecs from transport source ip in forward mode ecs trusted_listeners ecs trusted_client_cidrs trust gates for inbound ecs ecs use_for_plugin_targeting allow trusted inbound ecs to influence plugin targeting ip selection when ecs influences upstream selection targeting cache reads writes are bypassed to avoid cross subnet contamination legacy server enable_ede and server forward_local keys are still accepted as compatibility aliases server resolver timeouts recursion depth and resolver mode forward default forward to configured upstreams recursive walk from root servers master none authoritative only no forwarding cache miss refused server http admin web ui listener configuration 2 3 upstreams block upstreams describes how foghorn talks to other dns servers strategy failover try in order round_robin or random max_concurrent maximum simultaneous outstanding upstream queries endpoints list of upstream_host definitions notes if an upstream returns servfail malformed dns bytes or a mismatched response txid question foghorn treats that upstream as failed for that query and continues failover skip failover events are logged at debug but de duplicated per upstream until that upstream succeeds again to avoid log spam to surface these events set logging python level debug an upstream_host entry upstreams endpoints host 9 9 9 9 port 53 853 for dot transport udp udp tcp dot tls server_name dns quad9 net verify true true false an upstream_host entry using dns over http s upstreams endpoints transport doh url https dns example com dns query method post post get tls verify true true false ca_file etc ssl certs ca certificates crt 2 4 logging logging controls both the process wide python logger and the statistics query log backends python logging global defaults logging python level info debug info warn error critical stderr true true false file var foghorn log syslog false false true address facility tag plugins can also override logging per instance via their own logging block on the plugin entry using the same shape as logging python logging backends describes where persistent stats query log data is written each entry maps to a statistics backend such as sqlite or mqtt logging logging async true default async behaviour for stats backends query_log_only false false true backends id local log backend sqlite config db_path config var stats db batch_writes true id backup mqtt backend mqtt_logging config host mqtt internal port 1883 topic foghorn query_log 2 5 stats and query log the stats section controls runtime statistics behaviour and selects which logging backend to read from when logging async is true writes to stats query log backends are performed by a background worker so request handling stays fast setting it to false forces synchronous writes important fields include enabled master on off switch for statistics source_backend which logging backends id or backend alias to treat as the primary read backend example logging async true query_log_only false false true backends id local log backend sqlite config db_path config var stats db batch_writes true stats enabled true source_backend local log interval_seconds 300 ignore include_in_stats true just don t display them ignore_single_host false top_domains_mode suffix exact suffix top_domains example com query log flood hardening no code changes if query logging is enabled on an exposed resolver set explicit limits so flood traffic cannot grow persistence usage without bounds recommended controls logging query_log_retention global defaults max_records cap row count days cap age max_bytes cap estimated backend storage size prune_interval_seconds avoid pruning on every insert prune_every_n_inserts run prune on an insert cadence logging max_logging_queue keep async queue bounded default is bounded do not set 0 unless you explicitly want unbounded memory growth logging query_log_only when true skip mirroring aggregate counters to the persistence backend and keep only raw query log rows logging query_log_sampling enabled when false suppress persistent query log writes from the stats collector logging query_log_sampling sample_rate keep only a fraction of query log rows for example 0 1 for 10 logging query_log_sampling rate compatibility alias for sample_rate logging query_log_sample_rate legacy compatibility alias logging query_log_dedupe window_seconds suppress repeated identical query log rows inside a short window full hardening profile example_configs logging query_log_hardening yaml detailed guide docs query log hardening md rate limit integration rate plugin deny_log_first_n logs only the first n denies for each active blocked episode remaining deny events set plugindecision suppress_query_log and are skipped in persistent query logs until the episode cools down example hardening profile logging async true max_logging_queue 4096 query_log_only false query_log_retention max_records 500000 days 7 max_bytes 2147483648 prune_interval_seconds 30 prune_every_n_inserts 200 query_log_sampling sample_rate 0 25 query_log_dedupe window_seconds 2 max_entries 50000 backends id local log backend sqlite config db_path config var stats db per backend overrides optional retention_max_records 250000 retention_days 3 retention_max_bytes 1073741824 retention_prune_interval_seconds 15 retention_prune_every_n_inserts 100 backend specific optional maintenance controls sqlite retention_vacuum_on_prune retention_vacuum_interval_seconds sqlite_auto_vacuum none full incremental mongodb retention_native_ttl enables a ttl index when retention_days is set mysql mariadb retention_optimize_on_prune retention_optimize_interval_seconds postgresql retention_vacuum_on_prune retention_vacuum_interval_seconds 2 6 plugins in the plugins list each entry is a plugininstance plugins type filter id main filter enabled true setup abort_on_failure true hooks pre_resolve enabled true priority 50 logging level info config plugin specific config here you normally care about type short alias for the plugin id optional stable identifier for this plugin instance surfaced in stats logs and admin ui enabled whether it runs hooks per hook enable priority overrides optional setup one time setup behaviour abort_on_failure controls whether a failing setup aborts startup logging per plugin logging overrides level file stderr syslog using the same shape as the global logging block config the actual configuration for that plugin common plugin wide config options targeting preferred shape uses a nested targets block config targets object or legacy list string preferred object keys ips list string of cidr ips to target ignore_ips list string of cidr ips to exclude listeners list string of listeners udp tcp dot doh or aliases secure dot doh unsecure insecure udp tcp any null no restriction domains list string of domain names to match domains_mode exact or suffix defaults to suffix when domains is set qtypes list string of qtype names or for all types e g a aaaa opcodes list string of dns opcodes e g query rcodes list string of response codes for post resolve plugins e g noerror nxdomain legacy form if targets is a list string it is treated as targets ips logging per plugin logging the logging stanza on the plugin instance lets you bump log level or direct output differently from the global logger example with all common knobs plugins type some plugin id example enabled true logging level debug config targets ips 192 168 0 0 16 10 10 10 0 24 ignore_ips 192 168 0 10 listeners dot doh domains corp example domains_mode suffix exact suffix qtypes a aaaa opcodes query rcodes noerror nxdomain 3 listeners and upstreams by example 3 1 udp tcp listener a typical server listen dns configuration server listen dns udp enabled true host 0 0 0 0 port 53 tcp enabled true host 0 0 0 0 port 53 turn tcp off if you never want to accept tcp dns tcp enabled false true false 3 2 dns over tls dot upstream to talk to an upstream dot resolver upstreams strategy round_robin failover round_robin random endpoints host 1 1 1 1 port 853 transport dot tls server_name cloudflare dns com verify true you can mix dot and plain udp endpoints in the same list the strategy decides how they are chosen 3 3 dns over https doh listener with tls to expose a doh listener directly from foghorn for example on port 8053 with tls termination server listen dns udp dns tcp here doh enabled true host 0 0 0 0 port 8053 cert_file etc foghorn tls server crt key_file etc foghorn tls server key 3 4 doh listener behind an http reverse proxy when foghorn itself is running behind an http reverse proxy for example nginx or envoy you typically terminate tls at the proxy and run the doh listener as plain http on localhost the proxy handles https and forwards dns query to foghorn server listen dns udp dns tcp here doh enabled true host 127 0 0 1 port 8443 no cert_file key_file here tls is terminated at the reverse proxy your reverse proxy is then configured to listen on 443 with tls and proxy requests such as https dns example com dns query to http 127 0 0 1 8443 dns query 3 5 helper make targets for tls keys and certificates for quick local testing the makefile includes convenience targets that generate a small ca and server key material under keys make ssl ca create foghorn_ca key and a self signed foghorn_ca crt with ca key usage make ssl ca pem export the ca certificate as foghorn_ca pem for use as a trust anchor e g upstreams tls ca_file make ssl cert cname myserver create a server key and certificate signed by the local ca named foghorn_ cname key crt make ssl server pem cname myserver build a combined foghorn_ cname pem containing the server certificate and key use ca pem when foghorn is a tls client and needs to trust an internal ca for example for dot doh upstreams via tls ca_file use server pem when foghorn is acting as a tls server and you need a single file containing both cert and key for a listener these are intended for development and lab environments only for production use your normal pki or certificate management 4 plugin cookbook below are the built in plugins with short descriptions and minimal configs all examples assume they live in the shared plugins list 4 1 access control acl ip based allow deny control at the edge plugins type acl config default allow allow deny allow 192 168 1 1 overrides the deny below 10 0 0 0 8 deny 192 168 0 0 16 172 16 0 0 12 4 2 docker containers docker expose docker container names as dns answers plugins type docker config endpoints url unix var run docker sock url tcp my server lan 2375 ttl 60 health healthy running discovery true false true 4 3 hosts files hosts serve additional records from one or more hosts style files plugins type hosts config file_paths etc hosts config hosts tt...