How to Configure DNS on TrueNAS CORE and SCALE

TrueNAS sits at the center of your storage infrastructure, but misconfigured DNS can quietly break everything around it. Jails lose internet access, plugin updates fail silently, SMB shares stop resolving hostnames, and Active Directory joins crash with cryptic Kerberos errors. Whether you run TrueNAS CORE on FreeBSD or TrueNAS SCALE on Debian Linux, DNS is configured in one canonical place on the host — yet it ripples through every service, jail, VM, and containerized app on the system. Here is exactly how to get it right on both platforms.

Where TrueNAS Stores DNS Configuration

Both CORE and SCALE expose DNS under Network → Global Configuration. The relevant fields:

• Nameserver 1 / 2 / 3 — up to three recursive resolvers listed in priority order
• Domain — your primary DNS search domain (e.g. home.arpa, lan, or corp.example.com)
• Additional Domains (SCALE only) — extra search suffixes appended to /etc/resolv.conf

Whatever you enter here is written to /etc/resolv.conf on the host. On TrueNAS SCALE, systemd-resolved reads this file at startup. On TrueNAS CORE (FreeBSD), the system libc resolver uses it directly via resolv.conf(5). The critical caveat: both platforms silently overwrite /etc/resolv.conf whenever you save any network setting. Editing the file by hand fixes nothing permanently — the next save will clobber it.

Step-by-Step: DNS Configuration on TrueNAS CORE

TrueNAS CORE runs FreeBSD 13.x. All DNS configuration should happen through the web UI — the shell simply reflects what the UI writes.

1. Log into the web UI and navigate to Network → Global Configuration.
2. Under DNS Servers, fill in Nameserver 1 and Nameserver 2. Reliable defaults: 1.1.1.1 (Cloudflare) and 8.8.8.8 (Google). For home networks that need to resolve local hostnames, put your router's LAN IP first (e.g. 192.168.1.1) and a public resolver second as a fallback.
3. Set Domain to your local domain if you use one (e.g. local or home.arpa). Leave it blank for public-only resolution.
4. Click Save. TrueNAS immediately rewrites /etc/resolv.conf.
5. Open a shell via System → Shell or SSH and verify the changes took effect.

FreeBSD ships with host and nslookup pre-installed. The drill command — analogous to dig on Linux — is available if installed from the ports tree. For routine post-change verification, host is sufficient.

DNS Inside TrueNAS CORE Jails

Jails do not automatically inherit DNS changes made to the host after the jail was created. When you create a jail via Jails → Add, the wizard copies the current host resolver settings at creation time — but if you later update Global Configuration, running jails keep the resolver they started with.

To fix DNS inside an existing jail:

1. Go to Jails, expand the jail row, and click Shell to enter it.
2. Edit the jail's resolver: ee /etc/resolv.conf and set the correct nameservers. Changes inside a jail's own /etc/resolv.conf do persist — the jail owns its copy independently from the host.
3. Alternatively, use Jails → (jail name) → Edit → Jail Properties → Resolver to set the nameserver field through the UI without entering the shell.

Plugins such as Plex, Nextcloud, and Transmission run inside jails. If a plugin cannot reach the internet or an external API, stale jail-level DNS is the most common cause.

Step-by-Step: DNS Configuration on TrueNAS SCALE

TrueNAS SCALE runs Debian 12 (Bookworm) with a heavily customized systemd stack. The UI steps are identical to CORE, but the underlying mechanics differ in a few important ways.

1. Navigate to Network → Global Configuration.
2. Set Nameserver 1 and Nameserver 2 to real upstream resolver IPs. Do not enter 127.0.0.53 — that is the systemd-resolved stub listener, and pointing TrueNAS at it creates a circular resolution loop.
3. Set Domain and any Additional Domains you need for local hostname search.
4. Click Save. SCALE writes /etc/resolv.conf and updates the systemd-resolved configuration in tandem.

Verify from the shell after saving:

DNS for Apps and VMs on TrueNAS SCALE

TrueNAS SCALE Apps run on an embedded k3s (Kubernetes) cluster. CoreDNS inside k3s reads its upstream resolvers from the host at cluster startup. If you change DNS in Global Configuration while the cluster is already running, CoreDNS continues using the old servers until the Apps service is restarted.

To force CoreDNS to pick up updated resolver settings:

For Virtual Machines under Virtualization → Virtual Machines, TrueNAS does not inject DNS settings into the guest OS. Configure DNS inside each VM just as you would on any standalone machine — in Windows guest via Network Adapter properties, in Linux guests via /etc/resolv.conf or NetworkManager.

Root Causes of TrueNAS DNS Failures, Ranked by Frequency

When DNS breaks on TrueNAS, it is almost always one of these, in order of how often they appear in the wild:

1. Wrong nameserver IP entered. A single transposed digit — 1.1.1.10 instead of 1.1.1.1 — causes complete resolution failure with no useful error message anywhere in the UI. Always double-check entries and immediately confirm with cat /etc/resolv.conf after saving.
2. Router as sole nameserver with no fallback. Using your router's LAN IP (e.g. 192.168.1.1) as the only nameserver works when the router is healthy. If the router's DNS relay breaks, is filtered, or reboots, TrueNAS has nowhere to fall back. Always add a public resolver as Nameserver 2.
3. Stale DNS in jails or the k3s cluster after a host change. Changing Global Configuration does not propagate to running jails (CORE) or the k3s cluster (SCALE). Each keeps the resolver it was started with until explicitly restarted.
4. Domain controller not listed as Nameserver 1 in AD environments. Active Directory depends on SRV records hosted on the DC. Using a public resolver as primary breaks Kerberos and LDAP discovery even when general internet connectivity is working perfectly.
5. Firewall blocking outbound UDP/TCP port 53. Enterprise environments sometimes force all DNS through a policy-compliant server. Test directly: nc -zv 1.1.1.1 53. If that times out, the block is at the network level, not in TrueNAS configuration.
6. IPv6 nameserver entered with no working IPv6 route. Entering an IPv6 resolver address (e.g. 2606:4700:4700::1111) when your TrueNAS interface has no valid IPv6 default route causes every query to time out before failing over. Confirm with ping6 2606:4700:4700::1111 before configuring any IPv6 nameserver.

Active Directory Environments: DNS Rules That Cannot Be Skipped

When TrueNAS joins a Windows Active Directory domain, DNS is structural, not optional. The domain controller is the authoritative nameserver for the AD zone, hosting SRV records for Kerberos (_kerberos._tcp.domain), LDAP (_ldap._tcp.domain), and Global Catalog discovery (_gc._tcp.domain). Without those records, directory services fail at the lowest level regardless of general network health.

• Nameserver 1 must be the primary domain controller's IP. No exceptions. Public resolvers know nothing about your internal AD zone.
• Nameserver 2 should be the secondary DC if one exists — not a public resolver. A public resolver as Nameserver 2 will successfully answer general internet queries but will fail on all internal AD lookups.
• The Domain field in Global Configuration must exactly match the AD domain name (e.g. corp.example.com).

Verify that AD DNS is correctly populated before attempting a domain join in TrueNAS:

If either query returns SERVFAIL or an empty answer section, the problem is on the domain controller's DNS service. Fix it there before touching TrueNAS configuration.

How to Confirm the Fix Worked

After saving DNS changes and restarting any relevant services, run through this checklist before declaring the issue resolved:

1. From the TrueNAS shell: ping -c 3 google.com — should resolve and receive replies. A response confirms both DNS and routing are healthy.
2. Trigger an update check from the UI. In CORE: System → Update → Refresh. In SCALE: System Settings → Update → Check for Updates. This hits iXsystems' servers and fails loudly if DNS is still broken.
3. If you use plugins or Apps, open one and exercise a feature that makes outbound requests — Plex media matching, Nextcloud app store loading, or a container that pulls from an external API. Successful execution confirms the service-layer DNS is also working.
4. If the system is AD-joined, navigate to Directory Services → Active Directory and confirm the status shows Healthy. A status of No Connectivity or FAULTED after a DNS fix usually means the k3s restart or jail restart was skipped.
5. On CORE, verify a specific jail with: enter the jail shell and run host google.com. This confirms the jail-level resolver was also updated.

Common Misdiagnoses That Waste Time

• "The network card must be broken." If ping 1.1.1.1 (by IP address, no hostname) succeeds but ping google.com fails, the NIC, switch, and routing are entirely healthy. The problem is exclusively name resolution. Hardware is not involved.
• "Nothing changed, it just stopped working." DHCP lease renewal can silently replace the DNS servers assigned to TrueNAS by the router. Both CORE and SCALE default to DHCP on first install. If a static IP was never set, a DHCP pool change at the router can break resolution overnight without any logged event on TrueNAS.
• "The firewall must be blocking TrueNAS." Before investigating firewall rules, re-read /etc/resolv.conf. If the nameserver listed there is wrong or points to an unreachable address, no firewall changes will help. Confirm the file content matches what you entered in the UI before escalating.
• "SCALE behaves differently because of systemd-resolved." iXsystems configures systemd-resolved in stub resolver mode with /etc/resolv.conf as the authoritative source. It behaves identically to a traditional Debian resolver in practice. You do not need to manually edit /etc/systemd/resolved.conf — the TrueNAS UI manages it, and direct edits to that file will be overwritten on the next network save.

Preventing DNS Problems Going Forward

• Always configure two nameservers. A single-nameserver setup fails completely during any outage on that server. A public fallback costs nothing and prevents total resolution loss during router reboots or ISP DNS hiccups.
• Assign TrueNAS a static IP address. DHCP-assigned DNS can change without warning. Set a static address under Network → Interfaces → (your interface) → Edit and enter nameservers in Global Configuration manually rather than relying on DHCP-provided values.
• Export a config backup after every DNS change. CORE: System → General → Save Config. SCALE: System Settings → General → Download Config. The exported file includes your full network and DNS settings, making recovery from a bad configuration change fast and deterministic.
• Verify DNS after every major version upgrade. TrueNAS major upgrades occasionally reset portions of network configuration to defaults. A quick cat /etc/resolv.conf and ping google.com immediately after upgrading takes thirty seconds and can prevent hours of debugging.

2026 Update: IPv6, DoH, and DNSSEC on TrueNAS

Most residential and business ISPs have now deployed dual-stack IPv6, and TrueNAS handles it cleanly on both platforms. On SCALE, you can enter IPv6 nameserver addresses (e.g. 2606:4700:4700::1111 for Cloudflare, 2001:4860:4860::8888 for Google) in the Nameserver fields alongside IPv4 addresses. systemd-resolved prefers whichever address family has a working route. TrueNAS CORE works the same way — the FreeBSD resolver uses the IPv6 nameserver entry when an IPv6 default route exists on the interface. If IPv6 is partially configured on your network and queries to the IPv6 nameserver time out, remove the IPv6 entry and use IPv4-only until your network's IPv6 routing is confirmed stable.

DNS over HTTPS (DoH) and DNS over TLS (DoT) are not natively configurable at the TrueNAS host level in any current release, including SCALE 24.10 and CORE 13.3. The practical path to encrypted upstream DNS is running Unbound or AdGuard Home inside a CORE jail or a SCALE App container, configuring DoT or DoH upstream forwarding inside that service, and pointing TrueNAS Global Configuration nameservers at the container's local IP (e.g. 172.16.0.10). The TrueNAS host sends plain UDP/TCP queries to the local container; the container encrypts everything upstream. All jails and apps inherit the encrypted path transparently.

DNSSEC validation is not enforced by the TrueNAS host resolver by default on either platform. For environments where DNSSEC is a compliance requirement, run Unbound in a jail or container with val-permissive-mode: no disabled and use that container as your TrueNAS nameserver. All host and jail DNS queries then pass through the validating resolver before reaching upstream, and any response with a broken signature chain is rejected. For a foundational understanding of how DNS resolution works at the wire level — including the query/response format and resolver behavior that every implementation here follows — IETF RFC 1035 is the primary specification.