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
• CATEGORY_FILTER_ENABLED
• CATEGORY_FILTER_INDEX_URL
• CONFIG_PATH
• CONSUL_ALLOWLIST_URL
• CONSUL_DNSCHECK_KV_URL
• CONSUL_DNSCHECK_SESSION_URL
• CRASH_OUTPUT_DIR
• CRASH_OUTPUT_ENABLED
• CRASH_OUTPUT_PREFIX
• CUSTOM_DOMAINS_API_KEY
• CUSTOM_DOMAINS_CACHE_PATH
• CUSTOM_DOMAINS_ENABLED
• CUSTOM_DOMAINS_REFRESH_INTERVAL
• CUSTOM_DOMAINS_URL
• DNSCHECK_CACHE_KV_SIZE
• DNSCHECK_KV_TTL
• DNSCHECK_KV_TYPE
• 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_FORMAT
• LOG_TIMESTAMP
• MAX_THREADS
• METRICS_NAMESPACE
• NEW_REG_DOMAINS_ENABLED
• NEW_REG_DOMAINS_URL
• NODE_NAME
• PROFILES_API_KEY
• PROFILES_CACHE_PATH
• PROFILES_CACHE_TYPE
• PROFILES_URL
• REDIS_DB
• REDIS_HOST
• REDIS_KEY_PREFIX
• REDIS_MAX_ACTIVE
• REDIS_MAX_CONN_LIFETIME
• REDIS_MAX_IDLE
• REDIS_NETWORK
• REDIS_IDLE_TIMEOUT
• REDIS_PORT
• REDIS_WAIT
• QUERYLOG_PATH
• QUERYLOG_SEMAPHORE_ENABLED
• QUERYLOG_SEMAPHORE_LIMIT
• RATELIMIT_ALLOWLIST_TYPE
• RULESTAT_URL
• SAFE_BROWSING_ENABLED
• SAFE_BROWSING_URL
• SENTRY_DSN
• SESSION_TICKET_API_KEY
• SESSION_TICKET_CACHE_PATH
• SESSION_TICKET_INDEX_NAME
• SESSION_TICKET_REFRESH_INTERVAL
• SESSION_TICKET_TYPE
• SESSION_TICKET_URL
• STANDARD_ACCESS_API_KEY
• STANDARD_ACCESS_REFRESH_INTERVAL
• STANDARD_ACCESS_TIMEOUT
• STANDARD_ACCESS_TYPE
• STANDARD_ACCESS_URL
• 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.

CATEGORY_FILTER_ENABLED

Then set to 1, enable the category filter. When set to 0, disable it.

Default: 0.

CATEGORY_FILTER_INDEX_URL

The HTTP(S) URL or a hostless file URI (e.g. file:///tmp/category_filters.json) of the category 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 if CATEGORY_FILTER_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.

CRASH_OUTPUT_DIR

The path to the directory used to create crash reports. The directory must exist.

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

CRASH_OUTPUT_ENABLED

When set to 1, put a crash report to CRASH_OUTPUT_DIR.

Default: 0.

CRASH_OUTPUT_PREFIX

The prefix to use for the crash report files. The variable is required if CRASH_OUTPUT_ENABLED is set to 1.

Default: agdns.

CUSTOM_DOMAINS_API_KEY

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

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

CUSTOM_DOMAINS_CACHE_PATH

The path to directory for storing the downloaded certificate and private-key data.

Default: No default value, a valid directory path is required if CUSTOM_DOMAINS_ENABLED is set to 1.

CUSTOM_DOMAINS_ENABLED

When set to 1, enable the custom-domains feature. When set to 0, disable it.

Default: 1.

CUSTOM_DOMAINS_REFRESH_INTERVAL

The interval that defines how often to query the backend for the custom-domain data, as a human-readable duration.

Default: No default value, a positive value is required if CUSTOM_DOMAINS_ENABLED is set to 1.

Example: 1m

CUSTOM_DOMAINS_URL

The URL of the gRPC(S) API for the custom-domain data.

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

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 DNSCHECK_KV_TYPE is set to cache.

Example: 1000

DNSCHECK_KV_TTL

For how long to keep the information about a single user in remote KV, as a human-readable duration.

Default: Unset.

Example: 1m

DNSCHECK_KV_TYPE

Type of the remote KV storage. Allowed values are backend, cache, consul, and redis.

Default: Unset.

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.

Certificate validation requests to DoH servers are also proxied to this URL when both DoH and profiles are enabled.

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_FORMAT

The format for the server logs:

• text: Structured text format, it is the default value.

• default: Simple and human-readable plain-text format.

• json: JSON format.

• jsonhybrid: JSON with a schema consisting of level, msg, and time properties.

LOG_TIMESTAMP

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

Default: 1.

MAX_THREADS

If greater than zero, sets the maximum number of threads for the Go runtime. If zero, the number remains the default one, which is 10 000. It must not be negative.

Default: 0.

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.

NODE_NAME

The name of this server node. Used in debug DNS API and DNS checking.

Default: No default value, the variable is required.

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_INTERVAL

The interval between profiles cache file updates, as a human-readable duration. Setting this variable to a value less than refresh interval makes no sense, as the configured variable is checked only on the refresh intervals.

Default: No default value, the variable is required if PROFILES_CACHE_PATH is set to a non-none value.

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\
      filecachepb.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_CACHE_TYPE

Type of the profile cache. Allowed values are: default and opaque.

Default: No default value, the variable is required, if PROFILES_CACHE_PATH isn't set to none and configuration contains profiles.

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_DB

The index of Redis database to use.

Default: 0.

REDIS_HOST

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

Default: localhost, the variable is required if DNSCHECK_KV_TYPE is set to redis.

REDIS_KEY_PREFIX

The prefix for Redis keys.

Default: agdns.

REDIS_MAX_ACTIVE

The maximum number of active Redis connections.

Default: 100.

REDIS_MAX_CONN_LIFETIME

The maximum total duration of connections in a pool.

Default: 0s, which means that the lifetime is not limited.

REDIS_MAX_IDLE

The maximum number of idle Redis connections.

Default: 100.

REDIS_NETWORK

Kind of IP protocol version to use:

• ip means both;
• ip4 means IPv4 only;
• ip6 means IPv6 only.

All other values are invalid.

Default: ip4.

REDIS_IDLE_TIMEOUT

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

Default: 5m.

REDIS_PORT

Redis server port.

Default: 6379.

REDIS_WAIT

It selects if the pool must wait for a connection once the REDIS_MAX_ACTIVE limit is reached.

Default: 1, which means to wait.

QUERYLOG_PATH

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

Default: ./querylog.jsonl.

QUERYLOG_SEMAPHORE_ENABLED

If 1, enabled the querylog semaphore used to limit the parallelism of writing to the querylog and thus reducing the amount of OS threads that are created.

Default: 0.

QUERYLOG_SEMAPHORE_LIMIT

The amount of writes to the querylog that can run in parallel.

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

RATELIMIT_ALLOWLIST_TYPE

Defines where the rate limit settings are received from. Allowed values are backend and consul.

Default: Unset.

Example: consul.

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.

SESSION_TICKET_API_KEY

The API key to use when authenticating queries to the remote TLS session ticket storage, if SESSION_TICKET_TYPE is set to remote. The API key should be valid as defined by RFC 6750.

Default: Unset.

SESSION_TICKET_CACHE_PATH

The path to directory for storing downloaded TLS session tickets, when SESSION_TICKET_TYPE is set to remote. If directory doesn't exist, it will be created on first successful start.

Default: Unset.

SESSION_TICKET_INDEX_NAME

The base name of the file to store downloaded TLS session tickets index, when SESSION_TICKET_TYPE is set to remote. This name will invalidate the received tickets with the same name. If the file doesn't exist, it will be created on first successful start. The expected format of the file is as follows:

{
    "tickets": {
        "ticket_1": {
            "last_update": "2006-01-02T15:04:05.999999999Z07:00"
        },
        // …
        "ticket_n": {
            "last_update": "2006-01-02T15:04:10.999999999Z07:00"
        }
    }
}

Default: Unset.

SESSION_TICKET_REFRESH_INTERVAL

The interval between TLS session ticket rotations, as a human-readable duration.

Default: Unset.

SESSION_TICKET_TYPE

The type of TLS session ticket storage. Its possible values are: local and remote. When set to remote, the SESSION_TICKET_API_KEY, SESSION_TICKET_CACHE_PATH, SESSION_TICKET_INDEX_NAME, and SESSION_TICKET_URL variables are required.

Default: Unset.

SESSION_TICKET_URL

The base backend URL used as a TLS session ticket storage, when SESSION_TICKET_TYPE is set to remote. Supports gRPC(S) (grpc:// andgrpcs://) URLs. See the external API requirements section. The grpcs:// scheme is preferred because TLS session tickets are considered sensitive information.

Default: Unset.

STANDARD_ACCESS_API_KEY

The API key to use when authenticating requests to the standard access settings storage API, if STANDARD_ACCESS_TYPE is set to backend. The API key should be valid as defined by RFC 6750.

Default: Unset.

STANDARD_ACCESS_REFRESH_INTERVAL

The interval between standard access settings updates, when STANDARD_ACCESS_TYPE is set to backend, as a human-readable duration.

Default: Unset.

STANDARD_ACCESS_TIMEOUT

The timeout for standard access settings updates, when STANDARD_ACCESS_TYPE is set to backend, as a human-readable duration.

Default: Unset.

STANDARD_ACCESS_TYPE

The type of standard access settings storage. Its possible values are: off and backend. When set to backend, the STANDARD_ACCESS_API_KEY, STANDARD_ACCESS_REFRESH_INTERVAL, STANDARD_ACCESS_TIMEOUT, and STANDARD_ACCESS_URL variables are required.

Default: Unset.

STANDARD_ACCESS_URL

The base backend URL used as a standard access settings storage, when STANDARD_ACCESS_TYPE is set to backend. Supports gRPC(S) (grpc:// andgrpcs://) URLs. See the external API requirements section.

Default: Unset.

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.