dnsproxy Documentation

Run the container using the default configuration and expose the standard DNS ports (53/tcp and 53/udp).

docker run \
    --name dnsproxy \
    -p 53:53/tcp \
    -p 53:53/udp \
    adguard/dnsproxy

To get the latest stable version of the dnsproxy Docker image, use the docker pull command.

docker pull adguard/dnsproxy

You can install dnsproxy using one of the following methods:

1. Pre-built Binaries: Download the binary for your specific operating system and architecture from the GitHub Releases page.
2. Docker: Use the official Docker image from Docker Hub.
3. Build from Source: Requires Go 1.26 or later.

make build

To act as an encrypted server (e.g., providing DoH or DoT to clients), you must provide TLS certificates and specify the appropriate port using flags like --tls-port, --https-port, or --quic-port. Use -p 0 to disable plain DNS handling.

Note for DNSCrypt: You must first obtain a configuration file (e.g., using the dnscrypt tool) and provide it via --dnscrypt-config.

Use dnsmasq-like syntax to route queries for specific domains to specific upstreams using the -u flag.

Syntax: [/domain/]<upstreamString>

• [/domain/]upstream: Routes queries for domain and its subdomains to upstream.
• [/ *.domain/]upstream: The wildcard * matches any sub-domain, but not the domain itself.
• [/]upstream: The empty domain // matches unqualified names (single label) or DS requests.
• #: The special address # tells dnsproxy to use the common (default) servers.
• Precedence: More specific domains take precedence over less specific ones.

You can pass command-line arguments directly to the container to configure upstreams. In this example, the -u flag is used to specify Google DNS (8.8.8.8:53).

docker run \
    --name dnsproxy_google_dns \
    -p 53:53/tcp \
    -p 53:53/udp \
    adguard/dnsproxy \
    -u 8.8.8.8:53

To use a custom configuration file, mount your local config.yaml into the container at /opt/dnsproxy/config.yaml using a volume mount.

docker run \
    --name dnsproxy_google_dns \
    -p 53:53/tcp \
    -p 53:53/udp \
    -v $PWD/config.yaml:/opt/dnsproxy/config.yaml \
    adguard/dnsproxy

The CLI supports basic logging configuration via the following options:

• Log Output: You can specify a file path for logs. If provided, the application will create or append to the file with 0644 permissions. If not provided, logs are sent to os.Stdout.
• Verbosity: Enabling the Verbose flag sets the log level to Debug. By default, the log level is Info.

The proxy supports encrypted DNS via TLS and DoH.

TLS Configuration:

• Provide TLSCertPath and TLSKeyPath to enable TLS.
• Specify TLSListenPorts to define which ports the TLS server should listen on.

DoH Configuration:

• HTTP3 enables HTTP/3 support.
• DoHInsecureEnabled allows insecure DoH.
• HTTPSUserinfo can be used to provide credentials in user:password format.
• HTTPSListenPorts defines the ports for the DoH server.
• QUICListenPorts defines the ports for QUIC-based DoH.

The proxy supports DNS caching with the following configurable options:

• Cache: Enables or disables the cache.
• CacheSizeBytes: The maximum size of the cache in bytes.
• CacheMinTTL: Minimum Time To Live for cached records.
• CacheMaxTTL: Maximum Time To Live for cached records.
• CacheOptimistic: Enables optimistic cache responses.
• CacheOptimisticAnswerTTL: TTL for optimistic answers.
• CacheOptimisticMaxAge: Maximum age for optimistic cache entries.