NEXTDNS(1)

📦 version 1.47.3, in ubuntu stonking

💖 nextdns(1) — the manual, but make it make sense 💖

okay bestie, sit down, hydrate, because this is User Commands and it's about to be your new favorite daemon. This is the nextdns manual page, and yes I'm about to explain the whole thing to you like we're texting at 2am. 🫶

✨ NAME ✨

nextdns — a DNS-over-HTTPS proxy client for NextDNS and other DoH providers. 💅

🌈 SYNOPSIS 🌈

nextdns command [options]

🦋 DESCRIPTION 🦋

okay so. nextdns is a daemon. A daemon, bestie. It's a local DNS proxy, and it's literally the main character of your network stack. 👑

Here's the vibe: it catches standard DNS queries from your system on port 53 (both UDP and TCP, she's versatile 💅) and forwards them encrypted over HTTPS — that's DNS-over-HTTPS, DoH for short, iykyk — over to NextDNS servers or literally any other DoH provider you want. no cap.

The gorgeous part? Apps on your system need zero changes. They keep speaking plain, boring DNS to localhost like nothing happened, and nextdns quietly handles encryption, caching, filtering and logging behind the scenes. it's giving invisible guardian angel. ✨

The fancy filtering + analytics stuff requires a NextDNS account and a profile ID, which you get at https://nextdns.io. But also, lowkey, you can just use the daemon as a plain DoH client for any compatible provider. versatile queen. 👑

🎀 QUICK START 🎀

Step 1: Create a NextDNS account and grab your Profile ID:

https://nextdns.io

Step 2: Configure NextDNS before you start the service:

sudo nextdns config set -profile <profile-id>

Or, if you're feeling hands-on, edit the config file directly:

sudo editor /etc/nextdns.conf

Step 3: Enable and start the service:

sudo systemctl enable --now nextdns

Step 4: Verify the service is actually running (vibe check 🔍):

nextdns status
systemctl status nextdns

Step 5: Test DNS resolution through NextDNS:

dig @127.0.0.1 debian.org

if that resolves you ATE. 🍓

👑 COMMANDS 👑

here's the whole menu, babes:

  • install [options] — Not supported on Debian systems. 🙈 The service is managed by the package manager instead. To enable and start the service, use:
sudo systemctl enable --now nextdns
  • uninstall — Not supported on Debian systems. 😭 To remove the package, use:
sudo apt remove nextdns
  • start — Start the installed service. 🚀
  • stop — Stop the running service. 🛑
  • restart — Restart the running service. 🔄
  • status — Print the current service status (that's running, stopped, or not installed). 📊
  • log — Display the service logs. 📜
  • run [options] — Run the DNS proxy daemon in the foreground. Perfect for testing, or for environments where there's no service manager to handle things. See RUN OPTIONS below. 👇
  • config list — List all current configuration options and their values. 📝
  • config set [options] — Set one or more configuration options persistently. It accepts the exact same flags as run. Run nextdns config set -h for the full list. 🔧
  • config edit — Open the configuration file in your default editor. ✏️
  • config wizard — Run an interactive configuration wizard. 🧙 (magical)
  • activate — Configure the local system to use nextdns as its DNS resolver (writes to /etc/resolv.conf or configures systemd-resolved). 🌟
  • deactivate — Restore the original system DNS configuration. ↩️
  • discovered — Display the list of clients discovered on the local network via ARP, NDP, mDNS and DHCP, along with their resolved names and addresses. 🕵️♀️
  • cache-stats — Display hit/miss statistics for the local DNS cache. 🎯
  • cache-keys — Dump the list of domain names currently held in the local cache. 🗝️
  • trace — Print a full goroutine stack trace of the running daemon. Super useful for debugging hangs or unexpected behaviour. 🧵
  • arp — Dump the current ARP table (that's IPv4 address to MAC address mappings). 📇
  • ndp — Dump the current NDP table (IPv6 address to MAC address mappings). 📇
  • upgrade — Not supported on Debian systems. 💀 To upgrade, use:
sudo apt update && sudo apt install nextdns
  • version — Print the current version string. 🏷️

🔥 RUN OPTIONS 🔥

These are all the options that run accepts. Buckle up, there's a lot, and they're all important, so no skipping. 🫡

  • -profile ID — Your NextDNS profile ID (6 hexadecimal characters, e.g. ab12cd). The profile decides which filtering rules, blocklists and analytics apply to queries. This option may be repeated with a condition prefix to pick different profiles based on source subnet, MAC address, interface or user:
    • 10.0.3.0/24=abcdef — Apply profile abcdef to queries from the given IPv4 CIDR.
    • 2001:db8::/32=abcdef — Apply profile to queries from the given IPv6 CIDR.
    • 00:1c:42:2e:60:4a=abcdef — Apply profile to the host with the given MAC address.
    • eth0=abcdef — Apply profile to all hosts reachable through the given interface.
    • @alice=abcdef — On Linux (systemd-logind), macOS and Windows, apply profile when the interactive user is alice.
The first matching rule wins. periodt. 🏆
  • -listen addr — Address and port to listen on for DNS queries. May be repeated to listen on multiple addresses. Default: localhost:53. Example: 0.0.0.0:53. 📡
  • -setup-router — Configure nextdns for router mode: listen on all interfaces, set up DNS forwarding rules for the detected router type (OpenWrt, DD-WRT, EdgeOS, etc.) and undo all changes on exit. Heads up: when this option is active, the -listen option is ignored. 🙈
  • -auto-activate — Automatically run activate at startup and deactivate on exit, updating the system resolver configuration. 🔁
  • -cache-size size — Size of the in-memory DNS cache. Accepts units: kB, MB, GB. Set it to 0 to disable caching (that's the default). Example: 10MB. 💾
  • -cache-max-age duration — Maximum age for cached entries regardless of their TTL. Example: 1h. ⏳
  • -cache-metrics — Enable collection of cache hit/miss metrics, accessible via cache-stats. 📈
  • -max-ttl duration — Cap the TTL returned to clients. The internal cache still uses the true TTL for freshness evaluation. Useful together with -cache-size to make profile changes propagate faster to LAN clients. ⚡
  • -forwarder [domain=]addr[,addr...] — Forward queries for domain to the specified DNS server instead of NextDNS. If no domain is given, the forwarder acts as a catch-all fallback. May be repeated; first match wins. addr may be an IP[:port] for plain DNS or an HTTPS URL for DoH. A bootstrap IP may be appended after # for DoH addresses. Example: -forwarder corp.example.com=192.168.1.1. 🚚
  • -report-client-info — Attach device name, model and a short non-reversible ID to each query sent upstream. This enables per-device analytics in the NextDNS dashboard. 👀
  • -discovery-dns addr — DNS server used to resolve client names from IP addresses in router mode. Defaults to the server learned via DHCP. Only active when -report-client-info is set. 🔎
  • -mdns all|disabled|interface — Control mDNS-based client discovery. Use all (default) to listen on all interfaces, an interface name to restrict discovery, or disabled to turn it off entirely. 📶
  • -bogus-priv — Answer reverse lookups for private IP ranges (RFC 1918, RFC 4193) with NXDOMAIN instead of forwarding them upstream. Enabled by default. 🛡️
  • -detect-captive-portals — Fall back to plain DNS when a captive portal is detected, so the initial connection can succeed. Disabled by default. ⚠️ Warning: enabling this option may allow an attacker to force unencrypted DNS traffic. stay safe out there bestie.
  • -timeout duration — Maximum time to wait for an upstream response before failing. Default: 5s. ⏰
  • -max-inflight-requests n — Maximum number of concurrent in-flight requests. Default: 256. 🚦
  • -control path — Path to the Unix domain socket used by control commands (cache-stats, trace, arp, etc.). Default: /var/run/nextdns.sock. 🔌
  • -log-queries — Log every DNS query and its result to the system logger. 📝
  • -use-hosts — Consult /etc/hosts before sending queries upstream. Enabled by default. 📖
  • -debug — Enable verbose debug logging. 🐛
  • -config-file path — Path to an alternative configuration file. 🗂️

💫 EXAMPLES 💫

🍼 Getting started

Create a free account at https://nextdns.io and note your Profile ID (a 6-character hex string, e.g. ab12cd). Then configure and start the service:

# Set your profile
sudo nextdns config set -profile ab12cd

# Enable and start the service
sudo systemctl enable --now nextdns

# (Optional) Redirect system DNS to NextDNS
sudo nextdns activate

Check that the service is running:

nextdns status

🧪 Running in the foreground (testing)

Run the daemon interactively on a non-standard port, with caching and query logging enabled. This is chef's kiss for verifying behaviour before you commit to a permanent configuration:

sudo nextdns run -profile ab12cd -listen localhost:5454 \
    -cache-size 10MB -log-queries

In a second terminal, send a query and observe the response:

dig @127.0.0.1 -p 5454 example.com A

Repeat the same query to verify the cache is working — the query time should drop to 0 ms on the second and subsequent calls:

dig @127.0.0.1 -p 5454 example.com A    # first:  ~300 ms (upstream)
dig @127.0.0.1 -p 5454 example.com A    # second: ~0 ms   (cache hit)

🔍 Inspecting the cache

After the daemon has been running for a while (started with -cache-size), check how many queries were served from the local cache versus forwarded upstream:

nextdns cache-stats

Example output:

{
    "hit": 5,
    "miss": 11
}

To also collect detailed metrics (hits ratio, keys added/updated, etc.), start the daemon with both -cache-size and -cache-metrics:

sudo nextdns run -profile ab12cd -cache-size 10MB -cache-metrics

Then retrieve the extended counters at any time:

nextdns cache-metrics

⏱️ Controlling TTL handed to clients

Cap the TTL returned to LAN clients at 5 seconds so they always re-query the daemon (and pick up profile changes immediately) rather than caching answers themselves. The daemon's internal cache still honours the true TTL:

sudo nextdns run -profile ab12cd -cache-size 10MB -max-ttl 5s

🚫 bogus-priv: blocking private reverse lookups

By default, -bogus-priv is enabled. Reverse lookups for private IP ranges (RFC 1918, RFC 4193) are answered locally with NXDOMAIN and never forwarded upstream:

# returns NXDOMAIN immediately — not forwarded to NextDNS
dig @127.0.0.1 -p 5454 -x 192.168.1.1

# public IP — forwarded and resolved normally
dig @127.0.0.1 -p 5454 -x 8.8.8.8

To disable this behaviour (forward all reverse lookups upstream):

sudo nextdns run -profile ab12cd -bogus-priv=false

🌸 use-hosts: resolving /etc/hosts entries 💖

So with -use-hosts (which is on by default, bestie, you don't have to do anything), any query for a name that lives in /etc/hosts gets answered locally before anyone even thinks about going upstream. It's giving instant gratification.

Drop a local entry in like this:

# Add a local entry
echo '10.0.0.10 myserver.home' | sudo tee -a /etc/hosts

And then watch it get resolved instantly from /etc/hosts — 0 ms, zero upstream query, no cap:

# Resolved instantly from /etc/hosts, 0 ms, no upstream query
dig @127.0.0.1 -p 5454 myserver.home A

🦋 Split-horizon DNS with forwarders

Okay so you've got an internal corporate domain and you want that going to an on-premises DNS server while everything else goes to NextDNS. Very demure, very mindful:

sudo nextdns config set -profile ab12cd \
    -forwarder corp.example.com=192.168.1.1
sudo systemctl restart nextdns

Now say you want a DoH forwarder with a bootstrap IP for one specific domain. The bootstrap address is there to dodge that whole chicken-and-egg ✨situation✨ where the DoH hostname itself still needs to be resolved:

sudo nextdns config set -profile ab12cd \
    -forwarder internal.lan=https://doh.company.com#10.0.0.1
sudo systemctl restart nextdns

And listen — multiple forwarders get evaluated in order, and the first matching rule wins. Periodt:

sudo nextdns config set -profile ab12cd \
    -forwarder corp.example.com=192.168.1.1 \
    -forwarder lab.example.com=192.168.2.1
sudo systemctl restart nextdns

🌈 Using public DoH providers as forwarders

NextDNS can forward queries for specific domains to any public DNS-over-HTTPS resolver. The general format goes like this, bestie:

-forwarder DOMAIN=https://PROVIDER/dns-query

Here are the well-known public providers it supports — I'm putting the whole table in bullet form because tables are not the vibe here, but every single one is accounted for 👑

Forward example.com to Cloudflare and literally everything else to NextDNS:

sudo nextdns run -profile ab12cd \
    -forwarder example.com=https://cloudflare-dns.com/dns-query

Forward different domains to different providers at the same time, because why would you pick just one:

sudo nextdns run -profile ab12cd \
    -forwarder work.example.com=https://dns.google/dns-query \
    -forwarder games.example.com=https://dns.quad9.net/dns-query

Route all queries through a single public DoH provider with a wildcard rule, bypassing NextDNS entirely (main character energy, honestly):

sudo nextdns run -forwarder .=https://dns.quad9.net/dns-query

Add a bootstrap IP so you don't get stuck in circular resolution when the DoH hostname isn't reachable yet:

sudo nextdns run -profile ab12cd \
    -forwarder example.com=https://cloudflare-dns.com/dns-query#1.1.1.1

Define multiple servers for one domain to implement failover — they get tried left to right:

sudo nextdns run -profile ab12cd \
    -forwarder example.com=https://dns.quad9.net/dns-query,https://dns.google/dns-query
🫶 Wanna check the forwarder is actually active? Query the NextDNS metadata endpoint from a second terminal while the daemon is running. The proto field should read DOH.
dig @127.0.0.1 whoami.cloudflare TXT CH

The ADDITIONAL SECTION of that response is stuffed with metadata injected by the NextDNS daemon itself, and it's lowkey iconic:

profile.nextdns.io.   0  CH  TXT  "default"
client.nextdns.io.    0  CH  TXT  "203.0.113.10"
proto.nextdns.io.     0  CH  TXT  "DOH"
server.nextdns.io.    0  CH  TXT  "edgeuno-for-1"

👑 Per-device profiles (router mode)

Set it up as a router serving the whole LAN, with device-name discovery and per-device profile assignment by subnet:

sudo nextdns config set \
    -profile 10.0.1.0/24=ab12cd \
    -profile 10.0.2.0/24=ef34gh \
    -setup-router \
    -report-client-info
sudo systemctl enable --now nextdns

Assign a specific profile to a single device by MAC address:

sudo nextdns config set -profile ab12cd \
    -profile 00:1c:42:2e:60:4a=ef34gh \
    -setup-router -report-client-info
sudo systemctl restart nextdns

On Linux with systemd-logind, you can assign a profile per interactive user:

sudo nextdns config set \
    -profile @alice=ab12cd \
    -profile @bob=ef34gh
sudo systemctl restart nextdns

And to peek at the devices discovered on the LAN (that's ARP, NDP, mDNS and DHCP doing the work):

nextdns discovered

🩺 Diagnostics

Show the ARP table (IPv4 address → MAC mappings):

nextdns arp

Show the NDP table (IPv6 address → MAC mappings):

nextdns ndp

Print a goroutine stack trace of the running daemon — super useful when the daemon looks hung and you're like 😭:

nextdns trace

Follow the live service logs:

nextdns log

🎀 Managing the configuration file

List the current persistent configuration:

nextdns config list

Persistently enable caching and client reporting without reinstalling (we love a no-drama update):

sudo nextdns config set -cache-size 10MB -report-client-info
sudo nextdns restart

Open the configuration file in the default editor:

sudo nextdns config edit

✨ FILES ✨

  • /etc/nextdns.conf — the default configuration file, managed by nextdns config.
  • /var/run/nextdns.sock — the Unix domain control socket used for cache-stats, cache-keys, discovered, trace and similar commands.

💜 SEE ALSO 💜

systemctl(1), resolv.conf(5), dig(1)

NextDNS documentation and profile management: https://nextdns.io

🌸 AUTHOR 🌸

NextDNS Inc. <support@nextdns.io>

This manual page was written for the Debian package by Josenilson Ferreira da Silva <nilsonfsilva@hotmail.com>.

And that's the whole page, bestie — no crumbs left 💅 This one's from nextdns, dated 2026-06-02, and it's NEXTDNS(1) all the way down. Go forth and resolve responsibly 🦋✨

📦 where this page comes from