NextDNS DoH client
NextDNS CLI Client
This project is a DNS53 to DNS over HTTPS (DoH) proxy with advancedcapabilities to get the most out of NextDNS service. Although the mostadvanced features will only work with NextDNS, this program can workas a client for any DoH provider.
- Stub DNS53 to DoH proxy.
- Can run on single host or at router level.
- Multi upstream healthcheck / fallback.
- Conditional forwarder selection based on domain.
- Auto discovery and forwarding of LAN clients name and model.
- Conditional NextDNS configuration ID selection based onclient subnet prefix or MAC address.
- Auto detection of captive portals.
First, optain a configration ID on NextDNS.
Install the daemon
RPM Based Distributions (RedHat, Fedora, Centos, …)
sudo curl -s https://nextdns.io/yum.repo -o /etc/yum.repos.d/nextdns.reposudo yum install -y nextdns
Deb Based Distributions (Debian, Ubuntu, …)
wget -qO - https://nextdns.io/repo.gpg | sudo apt-key add -echo "deb https://nextdns.io/repo/deb stable main" | sudo tee /etc/apt/sources.list.d/nextdns.listsudo apt install apt-transport-https # only necessary on Debiansudo apt updatesudo apt install nextdns
Arch Linux (AUR)
sudo pacman -S yayyay -S nextdns
Install homebrew first.
brew install nextdns/tap/nextdns
go get -u github.com/nextdns/nextdnsgo install github.com/nextdns/nextdns
Setup and start NextDNS
Create a configuration id on NextDNS and use it here inplace of
sudo nextdns install -report-client-info -config
Note: if installed on a router, add
-listen :53 to have it listen on publicinterfaces.
Point resolver to NextDNS
Note: this command will alter your system DNS resolver configuration.
sudo nextdns activate
nextdns command is composed of sub commands:
“`Usage: nextdns [arguments]
The commands are:
install install service on the systemuninstall uninstall service from the systemstart start installed servicestop stop installed servicestatus return service statusrun run the daemonactivate setup the system to use NextDNS as a resolverdeactivate restore the resolver configurationversion show current version
status methods are to interactwith the OS service management system. It will be used to un/register andstart/stop the service.
The main sub-command to run the service is the
run command. The run commandcan be configured using options arguments or a configuration file (see[Configuration file] below.
install command takes the same arguments as the
run. Arguments used withthe
install command are used to call
run when the system starts the service.
install) sub-command takes the following arguments:
“` -bogus-priv 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.
-config value NextDNS custom configuration id.
The configuration id can be prefixed with a condition that is match for each query: * 10.0.3.0/24=abcdef: 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 Path to configuration file. (default “/etc/nextdns.conf”) -detect-captive-portals 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 [DOMAIN=]SERVER_ADDR[,SERVER_ADDR...]. A SERVER_ADDR can ben either an IP 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: https://dns.nextdns.io#18.104.22.168. Several servers can be specified, separated by comas to implement failover. This parameter can be repeated. The first match wins.
-hardened-privacy 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-queries Log DNS query. -report-client-info Embed clients information with queries. -timeout duration Maximum duration allowed for a request before failing (default 5s)“`
Once installed, the
activate sub-command can be used to configure the targetsystem DNS resolver to point on the local instance of
When installed on a router, nextdns can apply different configuration based onthe LAN client using conditional configuration parameters. The
-configparameter can be specified several times with different configuration IDs andconditions. Conditions can be subnet prefixes or MAC addresses.
If for instance, we want:* Clients in the
10.0.4.0/24 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
The install command would be as follow:
sudo nextdns run -listen :53 -report-client-info -config 10.0.4.0/24=12345 -config 00:1c:42:2e:60:4a=67890 -config abcdef
In case an internal domain is managed by a private DNS server, it is possible tosetup conditional forwarders. Conditional forwarders can be either plain oldDNS53 or DoH servers themselves. Several servers can be specified for failover andseveral with different domain can be used; the first match wins.
sudo nextdns run -listen :53 -report-client-info -config abcdef -forwarder mycompany.com=22.214.171.124,126.96.36.199 -forwarder mycompany2.com=https://doh.mycompany.com/dns-query#188.8.131.52
Integration with dnsmasq
It is possible to run dnsmasq and nextdns together and still benefit from clientreporting and conditional configuration:
- Make sure nextdns is installed on a different port using
-listen 127.0.0.1:5555for instance.
- Add the following settings to dnsmasq parameters:
--server '127.0.0.1#5555' --add-mac --add-subnet=32,128
Use with another DoH provider
The NextDNS DoH proxy can be used with other DoH providers by using theforwarder parameter with no condition:
sudo nextdns run -listen :53 -forwarder https://184.108.40.206/dns-query
At startup, nextdns reads /etc/nextdns.conf, if it exists. The format of thisfile consists of one option per line, exactly as the options accepted by the runsub-command without the leading
-. Lines starting with # are comments andignored.
Example configuration for NextDNS.
listen :5353report-client-info yes
config 10.0.4.0/24=12345config 00:1c:42:2e:60:4a=67890config abcdef
forwarder mycompany.com=220.127.116.11,18.104.22.168forwarder mycompany2.com=https://doh.mycompany.com/dns-query#22.214.171.124“`
To restore the repository download the bundle
git clone nextdns-nextdns_-_2019-12-03_11-03-55.bundle