How to install and configure our software

Follow this guide to learn how to install, configure and run our software for various operating systems.

Locked routers (no access to console)
Mobile app (Android only - iOS under development)
GUI software for Windows, MacOS, Linux (debian or RPM)
Proxy daemon/service
- Features
- Usage
  - Running as a daemon
  - Running as a service

Locked routers (no access to console)

With locked routers you will need to connect to our DNS server using the normal port 53. Unfortunately you lose any kind of encryption or caching with this method and you can only rely on the blocking abilities of DnsAdBlock of unwanted websites. Nothing too serious but we suggest investing in a new router that is not locked or keeping this point in mind for your next router purchase.

When connecting via the usual DNS port 53 we cannot authenticate you besides the info we receive from your requests, most importantly, your IP address. This is an issue when your IP address is dynamic (it changes after router restart, power failure etc). For this problem we have a solution explained in the How to update your connection details if you have a dynamic ip address post - scroll to the section titled: Using a dynamic DNS service such as DynDNS or NoIp

Mobile app

Only the Android app is currently available - iOS is under development

Our Android app can be found on Google Play. Install it and scan the QR code of the configuration you wish to use/connect to. The QR code can be found at the bottom of your configuration details.

GUI software for Windows, MacOS, Linux (debian or RPM)

If you're on Windows or want to use our GUI app please head over to the GUI installation instructions.

Proxy daemon/service

We support many operating systems and we're constantly adding to our list. If you don't find your OS here please contact us so we can add it.

To install our software is really easy. You can use our quick installer in your terminal:

sh -c 'sh -c "$(curl -sL https://api.dnsadblock.com/install)"'

If you don't want to execute content taken via curl (understandably so) please navigate to our list of supported operating systems. You will have separate guides there for every OS we support.

Features

Our proxy software has many features but here's the gist:

Proxies DNS:53 traffic to DNS over HTTPS
Runs on single host or on router level
Detection of router and setup
Detection of captive portals
Local cache with a user-defined size

Usage

After installing the proxy software you can set it up using the following commands:

Usage: dnsadblock <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 DnsAdBlock as a resolver
    deactivate      restore the resolver configuration
    version         show current version

dnsadblock can run as a daemon or as a service.

Most commands require sudo because dnsadblock will alter your network configuration settings

Running as a daemon

When running as a daemon you are responsible for managing its process. You can execute dnsadblock run -config someConfigId in your terminal and the process will start and stay up for as long as you have the terminal open.

The run command supports the following flags:

-auto-activate
Run activate at startup and deactivate on exit.

-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. (default true)

-cache-size string
Enables and set the size of the cache in bytes. Supports size units like (kB, MB, GB). Set it to a value of 0 to disable caching entirely. The cache is automatically flushed when the pointed configuration is updated. (default "0")

-cache-max-age duration
If set to more than 0, a cached entry will be considered stale after this duration, even if the record's TTL is higher.

-config value
Connection configuration id (from the connections list in your account).

The configuration id can be prefixed with a match condition 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
Custom path to configuration file.

-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[: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 follows:
https://dns.google/dns-query#8.8.8.8,2001:4860:4860::8888

Several servers can be specified, separated by comas to implement failover. This parameter can be repeated. The first match wins.

-listen string
Listen address for UDP DNS proxy server. (default "localhost:53")

-log-queries
Log DNS query.
Listen address for UDP DNS proxy server. (default "localhost:53")

-log-format
The output format of the logged queries.
The supported formats are 'text' and 'json'. The 'json' format is a lot more verbose and contains some extra fields as well

-report-client-info
Embed clients information with queries.

-setup-router
Automatically configures itself for a router setup.
Common types of router are detected to integrate gracefully. Changes applied are undone on daemon exit. The listen option is ignored when this option is used.

-use-hosts
Lookup /etc/hosts before sending queries to upstream resolver. (default true)

-proxy-address
Use a [http|socks5] proxy to perform DNS requests.
Provide a url in the form of: protocol://user:pass@host:port

Running as a service

To operate on a set it and forget it type we recommend using the install command. When running as a service use these commands to interact with the OS service management system:

The install and config command supports the same flags as the run command

install installs the service
uninstall removes the service
start starts the service (same as run)
stop stops the service
status returns status (running or not running)

sudo dnsadblock install -config someConfigId