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_ENABLED
• ADULT_BLOCKING_URL
• BACKEND_RATELIMIT_API_KEY
• BACKEND_RATELIMIT_URL
• BILLSTAT_API_KEY
• BILLSTAT_URL
• BLOCKED_SERVICE_ENABLED
• BLOCKED_SERVICE_INDEX_URL
• CONFIG_PATH
• CONSUL_ALLOWLIST_URL
• CONSUL_DNSCHECK_KV_URL
• CONSUL_DNSCHECK_SESSION_URL
• DNSCHECK_CACHE_KV_SIZE
• DNSCHECK_REMOTEKV_API_KEY
• DNSCHECK_REMOTEKV_URL
• FILTER_CACHE_PATH
• FILTER_INDEX_URL
• GENERAL_SAFE_ENABLED
• GENERAL_SAFE_SEARCH_URL
• GEOIP_ASN_PATH and GEOIP_COUNTRY_PATH
• LINKED_IP_TARGET_URL
• LISTEN_ADDR
• LISTEN_PORT
• LOG_TIMESTAMP
• METRICS_NAMESPACE
• NEW_REG_DOMAINS_ENABLED
• NEW_REG_DOMAINS_URL
• PROFILES_API_KEY
• PROFILES_CACHE_PATH
• PROFILES_URL
• REDIS_ADDR
• REDIS_KEY_PREFIX
• REDIS_MAX_ACTIVE
• REDIS_MAX_IDLE
• REDIS_IDLE_TIMEOUT
• REDIS_PORT
• QUERYLOG_PATH
• RULESTAT_URL
• SAFE_BROWSING_ENABLED
• SAFE_BROWSING_URL
• SENTRY_DSN
• SSL_KEY_LOG_FILE
• VERBOSE
• WEB_STATIC_DIR_ENABLED
• WEB_STATIC_DIR
• YOUTUBE_SAFE_SEARCH_ENABLED
• YOUTUBE_SAFE_SEARCH_URL

ADULT_BLOCKING_ENABLED

When set to 1, enable the adult-blocking hash-prefix filter. When set to 0, disable it.

Default: 1.

ADULT_BLOCKING_URL

The HTTP(S) URL of source list of rules for adult blocking filter.

Default: No default value, the variable is required if ADULT_BLOCKING_ENABLED is set to 1.

BACKEND_RATELIMIT_API_KEY

The API key to use when authenticating requests to the backend rate limiter API, if any. The API key should be valid as defined by RFC 6750.

Default: Unset.

BACKEND_RATELIMIT_URL

The base backend URL for backend rate limiter. Supports gRPC(S) (grpc:// and grpcs://) URLs. See the external API requirements section.

Default: No default value, the variable is required if the type of rate limiter is backend in the configuration file.

BILLSTAT_API_KEY

The API key to use when authenticating queries to the billing statistics API, if any. The API key should be valid as defined by RFC 6750.

Default: Unset.

BILLSTAT_URL

The base backend URL for backend billing statistics uploader API. Supports gRPC(S) (grpc:// and grpcs://) URLs. See the external HTTP API requirements section.

Default: No default value, the variable is required if there is at least one server group with profiles enabled.

BLOCKED_SERVICE_ENABLED

When set to 1, enable the blocked service filter. When set to 0, disable it.

Default: 1.

BLOCKED_SERVICE_INDEX_URL

The HTTP(S) 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 if BLOCKED_SERVICE_ENABLED is set to 1.

CONFIG_PATH

The path to the configuration file.

Default: ./config.yaml.

CONSUL_ALLOWLIST_URL

The HTTP(S) 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 if the type of rate limiter is consul in the configuration file.

CONSUL_DNSCHECK_KV_URL

The HTTP(S) 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 HTTP(S) 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

DNSCHECK_CACHE_KV_SIZE

The maximum number of the local cache key-value database entries for the DNS server checking.

Default: No default value, a positive value is required if the type of the database is set to cache.

Example: 1000

DNSCHECK_REMOTEKV_API_KEY

The API key to use when authenticating queries to the backend key-value database API, if any. The API key should be valid as defined by RFC 6750.

Default: Unset.

DNSCHECK_REMOTEKV_URL

The base backend URL used as a key-value database for the DNS server checking. Supports gRPC(S) (grpc:// andgrpcs://) URLs. See the external API requirements section.

Default: Unset.

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 HTTP(S) URL or a hostless file URI (e.g. file:///tmp/filters.json) 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_ENABLED

When set to 1, enable the general safe search filter. When set to 0, disable it.

Default: 1.

GENERAL_SAFE_SEARCH_URL

The HTTP(S) 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 if GENERAL_SAFE_SEARCH_ENABLED is set to 1.

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 HTTP(S) 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.

METRICS_NAMESPACE

The namespace to be used for Prometheus metrics. It must be a valid Prometheus metric label.

Default: dns.

NEW_REG_DOMAINS_ENABLED

When set to 1, enable the newly-registered domains hash-prefix filter. When set to 0, disable it.

Default: 1.

NEW_REG_DOMAINS_URL

The HTTP(S) URL of source list of rules for newly registered domains safe browsing filter.

Default: No default value, the variable is required if NEW_REG_DOMAINS_ENABLED is set to 1.

PROFILES_API_KEY

The API key to use when authenticating queries to the profiles API, if any. The API key should be valid as defined by RFC 6750.

Default: Unset.

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
  

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

Default: ./profilecache.pb.

PROFILES_MAX_RESP_SIZE

The maximum size of the response from the profiles API in a human-readable format.

Default: 64MB.

PROFILES_URL

The base backend URL for profiles API. Supports gRPC(S) (grpc:// and grpcs://) URLs. See the external API requirements section.

Default: No default value, the variable is required if there is at least one server group with profiles enabled.

REDIS_ADDR

Redis server address. Can be an IP address or a hostname.

Default: No default value, the variable is required if the type of remote KV storage for DNS server checking is redis in the configuration file.

REDIS_KEY_PREFIX

The prefix for Redis keys.

Default: agdns.

REDIS_MAX_ACTIVE

The maximum number of active Redis connections.

Default: 10.

REDIS_MAX_IDLE

The maximum number of idle Redis connections.

Default: 3.

REDIS_IDLE_TIMEOUT

How long until idle Redis connections are closed, as a human-readable duration.

Default: 30s.

REDIS_PORT

Redis server port.

Default: 6379.

QUERYLOG_PATH

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

Default: ./querylog.jsonl.

RULESTAT_URL

The HTTP(S) 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_ENABLED

When set to 1, enable the safe-browsing hash-prefix filter. When set to 0, disable it.

Default: 1.

SAFE_BROWSING_URL

The HTTP(S) URL of source list of rules for dangerous domains safe browsing filter.

Default: No default value, the variable is required if SAFE_BROWSING_ENABLED is set to 1.

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

• 2: Enables trace logging.

• 1: Enables debug logging.

• 0: The default level of verbosity: only info logs are printed.

Default: 0.

WEB_STATIC_DIR_ENABLED

When set to 1, use WEB_STATIC_DIR as the source of the static content.

Default: 0.

WEB_STATIC_DIR

The absolute path to the directory used to serve static content. The directory must exist.

The value of the Content-Type header is guessed from the files' contents. Other headers cannot be modified. If the content type of a file cannot be guessed, text/plain is used.

Default: No default value, the variable is required if WEB_STATIC_DIR_ENABLED is set to 1.

YOUTUBE_SAFE_SEARCH_ENABLED

When set to 1, enable the youtube safe search filter. When set to 0, disable it.

Default: 1.

YOUTUBE_SAFE_SEARCH_URL

The HTTP(S) 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 if YOUTUBE_SAFE_SEARCH_ENABLED is set to 1.