Skip to content
NextDNS CLI client (DoH Proxy)
Go Shell Dockerfile
Branch: master
Clone or download
Latest commit 4a7ed23 Jan 14, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Update Go version Jan 10, 2020
.goreleaser Remove failing upx (for now) Jan 7, 2020
arp Fix windows and add windows build Dec 13, 2019
config Add a generic router setup that just changes the listen to public Jan 2, 2020
discovery Fix merlin DHCP leases file path Jan 13, 2020
host Suppress non-error errors on macOS Jan 14, 2020
hosts Fix localhost resolution with Linux arch empty /etc/hosts Jan 2, 2020
internal/dnsmessage Revert "Remove direct dep on reflect" Jan 4, 2020
netstatus Log details about network change detected Dec 8, 2019
proxy Rewrite the zeroconf code to use dnsmessage instead miekg/dns Jan 2, 2020
resolver Use router's DNS to discover more names Jan 7, 2020
router Add missing file Jan 12, 2020
.bintray Slient curl output of bintray uploads Nov 23, 2019
.dockerignore Dockerfile (#7) Nov 9, 2019
.gitignore Add git ignore Nov 1, 2019
.goreleaser.yml Disable upx as it break many platforms Jan 4, 2020
Dockerfile Dockerfile (#7) Nov 9, 2019
LICENSE Add LICENSE file Nov 4, 2019 Use router's DNS to discover more names Jan 7, 2020
activate.go Fix activate with setup router Jan 13, 2020
config.go Add support for multiple router firmware Dec 29, 2019
go.mod Use router's DNS to discover more names Jan 7, 2020
go.sum Use router's DNS to discover more names Jan 7, 2020 Improve upgrade command for Jan 12, 2020
main.go Add support for multiple router firmware Dec 29, 2019
run.go Fix activate with setup router Jan 13, 2020
service.go Suppress non-error errors on macOS Jan 14, 2020

NextDNS CLI Client

This project is a DNS53 to DNS over HTTPS (DoH) proxy with advanced capabilities to get the most out of NextDNS service. Although the most advanced features will only work with NextDNS, this program can work as a client for any DoH provider.


First, optain a configration ID on NextDNS.

Then follow installation instruction for your platform or simply use our installer:

sh -c 'sh -c "$(curl -sL"'


  • Stub DNS53 to DoH proxy.
  • Auto discovery and forwarding of LAN clients name and model.
  • Supports a vast number of platforms / OS / routers.
  • Can run on single host or at router level.
  • Auto router setup (integrate with many different router firmware).
  • Serve from /etc/hosts.
  • Multi upstream healthcheck / fallback.
  • Conditional forwarder selection based on domain.
  • Conditional NextDNS configuration ID selection based on client subnet prefix or MAC address.
  • Auto detection of captive portals.

Supported Platforms

  • Linux: Redhat, Fedora, CentOS, Debian, Ubuntu, Arch
  • BSDs: FreeBSD, NetBSD, OpenBSD, DragonFly
  • MacOS
  • Windows
  • OpenWRT (with LuCI UI)
  • ASUS-Merlin
  • pfSense
  • Ubiquiti EdgeOS
  • VyOS
  • Synology
  • Entware (WIP)
  • DD-WRT (WIP)
  • OpnSense (soon)
  • Tomato (soon)
  • QNAP (soon)


The nextdns command is composed of sub commands:

Usage: nextdns <command> [arguments]

The commands are:

    install         install service on the system
    uninstall       uninstall service from the system
    start           start installed service
    stop            stop installed service
    restart         restart installed service
    status          return service status
    log             show service logs
    run             run the daemon
    config          manage configuration
    activate        setup the system to use NextDNS as a resolver
    deactivate      restore the resolver configuration
    version         show current version

The install, uninstall, start, stop and status methods are to interact with the OS service management system. It will be used to un/register and start/stop the service.

The run command starts the daemon in the foreground. It is meant to be called from an init script. Use the install command to install one.

The install command takes the same arguments as the run. Arguments used with the install command are used to call run when the system starts the service.

Once installed, you can edit the configuration using the config set command with the same argument as the run command.

The run, install and config sub-commands takes the following arguments:

    	Run activate at startup and deactivate on exit.
    	Bogus private reverse lookups.

    	All reverse lookups for private IP ranges (ie 192.168.x.x, etc.) are answered with
    	"no such domain" rather than being forwarded upstream. The set of prefixes affected
    	is the list given in RFC6303, for IPv4 and IPv6. (default true)
  -config value
    	NextDNS custom configuration id.

    	The configuration id can be prefixed with a condition that is match for each query:
    	* A CIDR can be used to restrict a configuration to a subnet.
    	* 00:1c:42:2e:60:4a=abcdef: A MAC address can be used to restrict configuration
    	 to a specific host on the LAN.

    	This parameter can be repeated. The first match wins.
  -config-file string
    	Custom path to configuration file.
    	Automatic detection of captive portals and fallback on system DNS to allow the connection.

    	Beware that enabling this feature can allow an attacker to force nextdns to disable DoH
    	and leak unencrypted DNS traffic.
  -forwarder value
    	A DNS server to use for a specified domain.

    	Forwarders can be defined to send proxy DNS traffic to an alternative DNS upstream
    	resolver for specific domains. The format of this parameter is

    	A SERVER_ADDR can ben either an IP[:PORT] for DNS53 (unencrypted UDP, TCP), or a HTTPS
    	URL for a DNS over HTTPS server. For DoH, a bootstrap IP can be specified as follow: Several servers can be specified, separated by
    	comas to implement failover.
    	This parameter can be repeated. The first match wins.
    	When enabled, use DNS servers located in jurisdictions with strong privacy laws.
    	Available locations are: Switzerland, Iceland, Finland, Panama and Hong Kong.
  -listen string
    	Listen address for UDP DNS proxy server. (default "localhost:53")
    	Log DNS query.
    	Embed clients information with queries.
    	Automatically configure NextDNS for a router setup.
    	Common types of router are detected to integrate gracefuly. Changes applies are
    	undone on daemon exit. The listen option is ignored when this option is used.
  -timeout duration
    	Maximum duration allowed for a request before failing. (default 5s)
    	Lookup /etc/hosts before sending queries to upstream resolver. (default true)

Once installed, the activate sub-command can be used to configure the target system DNS resolver to point on the local instance of nextdns. This is a convenience command to easily turn on and off nextdns on the host without killing the process.

Advanced Usages

Conditional Configuration

When installed on a router, nextdns can apply different configuration based on the LAN client using conditional configuration parameters. The -config parameter can be specified several times with different configuration IDs and conditions. Conditions can be subnet prefixes or MAC addresses.

If for instance, we want:

  • Clients in the subnet to have the 12345 configuration
  • The host with the 00:1c:42:2e:60:4a MAC address to have the 67890 configuration
  • The rest of the network to have the abcdef configuration

The install command would be as follow:

sudo nextdns install \
    -setup-router \
    -report-client-info \
    -config \
    -config 00:1c:42:2e:60:4a=67890 \
    -config abcdef

Note: the -setup-router will auto-detect the type of router and apply the appropriate changes to integrate with it.

Split Horizon

In case an internal domain is managed by a private DNS server, it is possible to setup conditional forwarders. Conditional forwarders can be either plain old DNS53 or DoH servers themselves. Several servers can be specified for failover and several with different domain can be used; the first match wins.

sudo nextdns install \
    -setup-router \
    -report-client-info \
    -config abcdef \
    -forwarder, \

Integration with dnsmasq

It is possible to run dnsmasq and nextdns together and still benefit from client reporting and conditional configuration:

  • Make sure nextdns is installed on a different port using -listen for instance.
  • Add the following settings to dnsmasq parameters: --server '' --add-mac --add-subnet=32,128

Use with another DoH provider

The NextDNS DoH proxy can be used with other DoH providers by using the forwarder parameter with no condition:

sudo nextdns install \
    -listen :53 \

Configuration file

At startup, nextdns reads its on disk configuration. The format of this file consists of one option per line, exactly as the options accepted by the run sub-command without the leading -. Lines starting with # are comments and ignored.

Example configuration:

# Example configuration for NextDNS.

listen :5353
setup-router yes
report-client-info yes

config 00:1c:42:2e:60:4a=67890
config abcdef


Location and sometimes format of the configuration can vary from system to system. It is advised to use the nextdns config list and nextdns config set commands to interact with the configuration.

You can’t perform that action at this time.