AdGuardDNS/doc/environment.md

AdGuard DNS Environment Configuration

AdGuard DNS uses environment variables to store some of the more sensitive configuration. All other configuration is stored in the configuration file.

Contents

• ADULT_BLOCKING_URL
• BILLSTAT_URL
• BLOCKED_SERVICE_INDEX_URL
• CONSUL_ALLOWLIST_URL
• CONSUL_DNSCHECK_KV_URL
• CONSUL_DNSCHECK_SESSION_URL
• CONFIG_PATH
• FILTER_INDEX_URL
• FILTER_CACHE_PATH
• GENERAL_SAFE_SEARCH_URL
• GEOIP_ASN_PATH and GEOIP_COUNTRY_PATH
• LINKED_IP_TARGET_URL
• LISTEN_ADDR
• LISTEN_PORT
• LOG_TIMESTAMP
• NEW_REG_DOMAINS_URL
• PROFILES_CACHE_PATH
• PROFILES_URL
• QUERYLOG_PATH
• RESEARCH_METRICS
• RESEARCH_LOGS
• RULESTAT_URL
• SAFE_BROWSING_URL
• SENTRY_DSN
• SSL_KEY_LOG_FILE
• VERBOSE
• YOUTUBE_SAFE_SEARCH_URL

ADULT_BLOCKING_URL

The URL of source list of rules for adult blocking filter.

Default: No default value, the variable is required.

BILLSTAT_URL

The base backend URL for backend billing statistics uploader API. The backend endpoints must reply with a 200 status code on success. See the external HTTP API requirements section

Default: No default value, the variable is required.

BLOCKED_SERVICE_INDEX_URL

The URL of the blocked service index file server. See the external HTTP API requirements section on the expected format of the response.

Default: No default value, the variable is required.

CONFIG_PATH

The path to the configuration file.

Default: ./config.yaml.

CONSUL_ALLOWLIST_URL

The URL of the Consul instance serving the dynamic part of the rate-limit allowlist. See the external HTTP API requirements section on the expected format of the response.

Default: No default value, the variable is required.

CONSUL_DNSCHECK_KV_URL

The URL of the KV API of the Consul instance used as a key-value database for the DNS server checking. It must end with /kv/<NAMESPACE> where <NAMESPACE> is any non-empty namespace. If not specified, the CONSUL_DNSCHECK_SESSION_URL is also omitted.

Default: Unset.

Example: http://localhost:8500/v1/kv/test

CONSUL_DNSCHECK_SESSION_URL

The URL of the session API of the Consul instance used as a key-value database for the DNS server checking. If not specified, the CONSUL_DNSCHECK_KV_URL is also omitted.

Default: Unset.

Example: http://localhost:8500/v1/session/create

FILTER_CACHE_PATH

The path to the directory used to store the cached version of all filters and filter indexes.

Default: ./filters/.

FILTER_INDEX_URL

The URL of the filtering rule index file server. See the external HTTP API requirements section on the expected format of the response.

Default: No default value, the variable is required.

GENERAL_SAFE_SEARCH_URL

The URL of the list of general safe search rewriting rules. See the external HTTP API requirements section on the expected format of the response.

Default: No default value, the variable is required.

GEOIP_ASN_PATH and GEOIP_COUNTRY_PATH

Paths to the files containing MaxMind GeoIP databases: for ASNs and for countries and continents respectively.

Default: ./asn.mmdb and ./country.mmdb.

LINKED_IP_TARGET_URL

The target URL to which linked IP API requests are proxied. In case linked IP and dynamic DNS web server is configured, the variable is required. See the external HTTP API requirements section.

Default: Unset.

LISTEN_ADDR

The IP address on which to bind the debug HTTP API.

Default: 127.0.0.1.

LISTEN_PORT

The port on which to bind the debug HTTP API, which includes the health check, Prometheus, pprof, and other endpoints.

Default: 8181.

LOG_TIMESTAMP

If 1, show timestamps in the plain text logs. If 0, don't show the timestamps.

Default: 1.

NEW_REG_DOMAINS_URL

The URL of source list of rules for newly registered domains safe browsing filter.

Default: No default value, the variable is required.

PROFILES_CACHE_PATH

The path to the profile cache file:

• none means that the profile caching is disabled.

• A file with the extension .pb means that the profiles are cached in the protobuf format.

  Use the following command to inspect the cache, assuming that the version is correct:

  protoc\
      --decode\
      profiledb.FileCache\
      ./internal/profiledb/internal/filecachepb/filecache.proto\
      < /path/to/profilecache.pb
  

• A file with the extension .json means that the profiles are cached in the JSON format. This format is deprecated and is not recommended.

The profile cache is read on start and is later updated on every full refresh.

Default: ./profilecache.json.

PROFILES_URL

The base backend URL for profiles API. The backend endpoints must reply with a 200 status code on success. See the external HTTP API requirements section.

Default: No default value, the variable is required.

QUERYLOG_PATH

The path to the file into which the query log is going to be written.

Default: ./querylog.jsonl.

RESEARCH_METRICS

If 1, enable collection of a set of special prometheus metrics (prefix is dns_research). If 0, disable collection of those metrics.

Default: 0.

RESEARCH_LOGS

If 1, enable logging of additional info that may be required for research purposes (prefix research:). The log will only be written when RESEARCH_METRICS is also set to 1. If 0, disable logging of this info.

Default: 0.

RULESTAT_URL

The URL to send filtering rule list statistics to. If empty or unset, the collection of filtering rule statistics is disabled. See the external HTTP API requirements section on the expected format of the response.

Default: Unset.

Example: https://stats.example.com/db

SAFE_BROWSING_URL

The URL of source list of rules for dangerous domains safe browsing filter.

Default: No default value, the variable is required.

SENTRY_DSN

Sentry error collector address. The special value stderr makes AdGuard DNS print these errors to standard error.

Default: stderr.

SSL_KEY_LOG_FILE

If set, TLS key logs are written to this file to allow other programs (i.e. Wireshark) to decrypt packets. Must only be used for debug purposes.

Default: Unset.

VERBOSE

When set to 1, enable verbose logging. When set to 0, disable it.

Default: 0.

YOUTUBE_SAFE_SEARCH_URL

The URL of the list of YouTube-specific safe search rewriting rules. See the external HTTP API requirements section on the expected format of the response.

Default: No default value, the variable is required.