Skip to content

AdguardTeam/AdGuardDNSClient

Repository files navigation

AdGuard DNS Client

AdGuard DNS Logo

Screenshot showing the logs of 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.

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.
  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'

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"

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

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.

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

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

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;

Option -v enables the verbose log output.

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

The YAML configuration file is described in its own article, and there is also a sample configuration file config.dist.yaml. Some configuration parameters can also be overridden using the environment.

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.