AdGuard DNS Client

A cross-platform lightweight DNS client for AdGuard DNS. It operates as a DNS server that forwards DNS requests to the corresponding upstream resolvers.

Quick start

Warning

AdGuard DNS Client is still in the Beta stage. It may be unstable.

Supported operating systems:

• Linux;
• macOS;
• Windows.

Supported CPU architectures:

• 64-bit ARM;
• AMD64;
• i386.

Getting started

Unix-like

1. Download and unpack the .tar.gz or .zip archive from the releases page.

   [!WARNING] On macOS, it's crucial that globally installed daemons are owned by root (see the launchd documentation), so the AdGuardDNSClient executable must be placed in the /Applications/ directory or its subdirectory.

2. Install it as a service by running:

   ./AdGuardDNSClient -s install -v

3. Edit the configuration file config.yaml.

4. Start the service:

   ./AdGuardDNSClient -s start -v

To check that it works, use any DNS checking utility. For example, using nslookup:

nslookup -debug 'www.example.com' '127.0.0.1'

Windows

Just download and install using the MSI installer from the releases page.

To check that it works, use any DNS checking utility. For example, using nslookup.exe:

nslookup -debug "www.example.com" "127.0.0.1"

Developing and contributing

See CONTRIBUTING.md for more details on how to contribute.

Development quick start

You will need Go 1.22 or later. First, register our pre-commit hooks:

make init

Then, install the necessary tools and dependencies:

make go-deps go-tools

That’s pretty much it! You should now be able to lint, test, and build the AdGuardDNSClient binary:

make go-lint
make go-test
make go-build

For building packages, you might need additional tools, such as GnuPG, MSI Tools (v0.103 and later), etc. See ./scripts/make/build-release.sh.

Command-line options

Each option overrides the corresponding value provided by the configuration file and the environment.

Help

Option -h makes AdGuard DNS Client print out a help message to standard output and exit with a success status-code.

Service

Option -s <value> specifies the OS service action. Possible values are:

• install: installs AdGuard DNS Client as a service;
• restart: restarts the running AdGuard DNS Client service.
• start: starts the installed AdGuard DNS Client service;
• status: shows the status of the installed AdGuard DNS Client service;
• stop: stops the running AdGuard DNS Client;
• uninstall: uninstalls AdGuard DNS Client service;

Verbose

Option -v enables the verbose log output.

Version

Option --version makes AdGuard DNS Client print out the version of the AdGuardDNSClient executable to standard output and exit with a success status-code.

Configuration

The YAML configuration file is described in the doc/configuration.md file, and there is also a sample configuration file config.dist.yaml. Some configuration parameters can also be overridden using the environment, see doc/environment.md.

Exit codes

There are a few different exit codes that may appear under different error conditions:

• 0: Successfully finished and exited, no errors.

• 1: Internal error, most likely a misconfiguration.

• 2: Bad command-line argument or value.