Skip to main content
Beta. This feature is off by default and may change. It needs mesh networking to be on. Docker only forwards a container’s lookups to port 53 of the DNS server address it is given. Without an explicit address, a container asks the host’s own resolver, and the mesh DNS server never sees the query. This setting closes that gap on the node that runs the control plane.

Turn it on

Set dns.mesh_resolver_enabled to true (Settings, levelrail-cli settings set, or the API). It applies live. The environment variable LEVELRAIL_DNS_MESH_RESOLVER_ENABLED only seeds the default. When it is on, the node:
  • Binds the mesh DNS server to each Levelrail-managed bridge gateway address on port 53 (udp and tcp). Never 0.0.0.0, and never the host’s own 127.0.0.53 or 127.0.0.54 stub.
  • Answers only containers on those bridges and the mesh. Any other source gets REFUSED.
  • Adds an INPUT accept for udp and tcp 53 from each managed bridge interface, tagged with a comment so it can be found and removed. It uses iptables, or nft when iptables is missing. Turning the setting off removes it.
  • Sets the DNS servers of app containers created from then on to the gateway address plus a fallback (see below), but only after that listener is confirmed. Existing containers pick it up when they are recreated.
The bridge list is re-read every dns.mesh_resolver_interval (15 seconds by default), so a new network gets a listener and a rule without a restart.

Public names

Names outside the mesh zone are forwarded to the host’s own upstream resolvers, so a container that points at the gateway keeps resolving public names. With dns.forward_enabled off, the gateway refuses them and the container relies on its fallback server alone.
  • Upstreams come from dns.forward_upstreams when set, else from /run/systemd/resolve/resolv.conf when that file exists, else /etc/resolv.conf. The systemd loopback stub is skipped when the real upstream file exists, and the gateway’s own addresses are never used, so the host resolver cannot point back at it.
  • Queries go over UDP and retry over TCP when the answer is truncated. An upstream that times out or fails the network is tried last next time. SERVFAIL and REFUSED from an upstream are passed on as answers and do not count against it.
  • Forwarded queries carry a small EDNS option naming this node. A query that arrives with this node’s own tag is dropped and counted, which breaks a resolver loop.
  • Answers are cached in memory, up to dns.cache_bytes (4 MiB by default, 0 turns the cache off). TTLs are clamped by dns.cache_max_ttl. A name-does-not-exist answer is cached only when it carries an SOA record, for at most dns.cache_negative_max_ttl. SERVFAIL is never cached.
  • Each container may cause dns.rate_limit_qps upstream lookups per second (dns.rate_limit_burst at once). Cached answers do not count. Excess queries get REFUSED.
  • The query log shows the reasons forwarded, cached and upstream_failed next to the existing ones.
Each has an environment variable LEVELRAIL_ plus the upper case key (for example LEVELRAIL_DNS_CACHE_BYTES) that only seeds the first value.

When it falls back

The control plane never points a container at an address that is not listening.
  • If port 53 on a gateway address is taken, that listener is skipped, a log line carries the reason dns_bind_in_use, and containers there keep Docker’s resolver. The mesh server on its own unprivileged port keeps running.
  • dns_bind_denied means the process may not bind port 53; run it as root or lower the unprivileged port start.
  • New containers also get a second DNS server: the first host upstream that a container can reach (dns.container_fallback, host_upstream by default). When the Levelrail process is stopped or restarted, nothing listens on the gateway, the connection is refused at once, and Docker moves on to that server, so lookups keep working. The honest limit: queries during that gap go to the fallback and are not attributed to an app in the query log. A host whose only resolver is the loopback stub has no usable fallback, so those containers get the gateway alone. Set none to keep only the gateway.
  • Remote nodes are never given the control plane’s gateway address, because no agent runs a resolver yet. Their containers keep Docker’s defaults.

Firewall note

Many hosts end the INPUT chain in a REJECT rule (the default on several cloud images). Without the accept, containers cannot reach a listener on the gateway, and each lookup waits several seconds. If you manage the firewall yourself, add an accept for udp and tcp 53 from the Levelrail bridge interfaces.

Check it

levelrail-cli doctor shows three rows while the setting is on: whether the listeners are bound (with the coded reason when not), whether the INPUT accept is present on every managed bridge, and how many app containers on this node use the resolver. To see which app asked for what, turn on DNS query visibility.
Last modified on November 16, 2026