malhuda/AdGuardDNS
1
0
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardDNS.git synced 2025-02-20 11:23:36 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
AdGuardDNS/doc/configuration.md
Andrey Meshkov 328512e850 Sync v2.0.1
2022-09-07 20:18:00 +03:00

32 KiB
Raw Permalink Blame History

AdGuard DNS Configuration File

Besides the environment, AdGuard DNS uses a YAML file to store configuration. See file config.dist.yml for a full example of a configuration file with comments.

Contents

Rate Limiting

The ratelimit object has the following properties:

  • refuseany: If true, refuse DNS queries with the ANY (aka *) type.

    Example: true.

  • response_size_estimate: The size of one DNS response for the purposes of rate limiting. If a DNS response is larger than this value, it is counted as several responses.

    Example: 1KB.

  • back_off_period: The time during which to count the number of requests that a client has sent over the RPS.

    Example: 10m.

  • back_off_duration: How long a client that has hit the RPS too often stays in the backoff state.

    Example: 30m.

  • rps: The rate of requests per second for one subnet. Requests above this are counted in the backoff count.

    Example: 30.

  • back_off_count: Maximum number of requests a client can make above the RPS within a back_off_period. When a client exceeds this limit, requests aren't allowed from client's subnet until back_off_duration ends.

    Example: 1000.

  • allowlist: The allowlist configuration object. It has the following fields:

    • list: The array of the allowed IPs or CIDRs.

      Property example:

      'list':
  - '192.168.1.4'
  - '192.175.2.1/16'

    • refresh_interval: How often AdGuard DNS refreshes the dynamic part of its allowlist from the data received from the CONSUL_URL, as a human-readable duration.

      Example: 30s.

  • ipv4_subnet_key_len: The length of the subnet prefix used to calculate rate limiter bucket keys for IPv4 addresses.

    Example: 24.

  • ipv6_subnet_key_len: Same as ipv4_subnet_key_len above but for IPv6 addresses.

    Example: 48.

For example, if back_off_period is 1m, back_off_count is 10, and rps is 5, a client (meaning all IP addresses within the subnet defined by ipv4_subnet_key_len and ipv6_subnet_key_len) that made 15 requests in one second or 6 requests (one above rps) every second for 10 seconds within one minute, the client is blocked for back_off_duration.

Cache

The cache object has the following properties:

  • type: The type of cache to use. Can be simple (a simple LRU cache) or ecs (a ECS-aware LRU cache). If set to ecs, ecs_size must be greater than zero.

    Example: simple.

  • size: The total number of items in the cache for hostnames with no ECS support. Must be greater than or equal to zero. If zero, cache is disabled.

    Example: 10000.

  • ecs_size: The total number of items in the cache for hostnames with ECS support.

    Example: 10000.

Upstream

The upstream object has the following properties:

  • server: The address of the main upstream server, in the ip:port format.

    Example: 8.8.8.8:53 or [2001:4860:4860::8844]:53.

  • timeout: Timeout for all outgoing DNS requests, as a human-readable duration.

    Example: 2s.

  • fallback: The array of addresses of the fallback upstream servers, in the ip:port format. These are use used in case a network error occurs while requesting the main upstream server.

    Example: ['1.1.1.1:53', '[2001:4860:4860::8888]:53'].

  • healthcheck: Healthcheck configuration. See below.

Healthcheck

If enabled is true, the upstream healthcheck is enabled. The healthcheck worker probes the main upstream with an A query for a domain created from domain_template. If there is an error, timeout, or a response different from a NOERROR one then the main upstream is considered down, and all requests are redirected to fallback upstream servers for the time set by backoff_duration. Afterwards, if a worker probe is successful, AdGuard DNS considers the connection to the main upstream as restored, and requests are routed back to it.

  • enabled:

    If true, the upstream healthcheck is enabled.

    Example: true.

  • interval: How often AdGuard DNS makes upstream healthcheck requests, as a human-readable duration.

    Example: 2s.

  • timeout: Timeout for all outgoing healthcheck requests, as a human-readable duration.

    Example: 1s.

  • backoff_duration: Backoff duration after failed healthcheck request, as a human-readable duration. If the main upstream is down, AdGuardDNS does not return back to using it until this time has passed. The healthcheck is still performed, and each failed check advances the backoff.

    Example: 30s.

  • domain_template: The template for domains used to perform healthcheck queries. If the domain_template contains the string ${RANDOM}, all occurrences of this string are replaced with a random string (currently, a hexadecimal form of a 64-bit integer) on every healthcheck query. Queries must return a NOERROR response.

    Example: ${RANDOM}.neverssl.com.

Backend

The backend object has the following properties:

  • timeout: Timeout for all outgoing HTTP requests to the backend, as a human-readable duration. Set to 0s to disable timeouts.

    Example: 10s.

  • refresh_interval: How often AdGuard DNS checks the backend for data updates, as a human-readable duration.

    Example: 1m.

  • full_refresh_interval: How often AdGuard DNS performs full synchronization, as a human-readable duration.

    Example: 24h.

  • bill_stat_interval: How often AdGuard DNS sends the billing statistics to the backend, as a human-readable duration.

    Example: 1m.

Query Log

The query_log object has the following properties:

  • file: The file query log configuration object. It has the following properties:

    • enabled: If true, the JSONL file query logging is enabled.

      Property example:

      'file':
    'enabled': true

GeoIP Database

The geoip object has the following properties:

  • host_cache_size: The size of the host lookup cache, in entries.

    Example: 100000.

  • ip_cache_size: The size of the IP lookup cache, in entries.

    Example: 100000.

  • refresh_interval: Interval between the GeoIP database refreshes, as a human-readable duration.

    Example: 5m.

DNS Server Check

The check object has the following properties:

  • domains: The domain suffixes to which random IDs are prepended using a hyphen.

    Property example:

    'domains':
  - 'dnscheck.example.com'
  - 'checkdns.example.com'

  • node_location: The location code of this server node.

    Example: ams.

  • node_name: The name of this server node.

    Example: eu-1.dns.example.com.

  • ttl: For how long to keep the information about a single user in Consul KV, as a human-readable duration. Note the actual TTL may be up to twice as long due to Consul's peculiarities.

    Example: 30s.

  • ipv4 and ipv6: Arrays of IPv4 or IPv6 addresses with which to respond to A and AAAA queries correspondingly. Generally, those should be the IP addresses of the AdGuard DNS main HTTP API for the DNS server check feature to work properly. In a development setup, that means the localhost addresses.

    Property examples:

    'ipv4':
  - '1.2.3.4'
  - '5.6.7.8'
'ipv6':
  - '1234::cdee'
  - '1234::cdef'

Web API

The optional web object has the following properties:

  • linked_ip: The optional linked IP and dynamic DNS (DDNS, DynDNS) web server configuration. The static content is not served on these addresses.

    See the full description of this API on the HTTP API page.

    Property bind has the same format as non_doh_bind below.

    Property example:

    'linked_ip':
    'bind':
      - 'address': '127.0.0.1:80'
      - 'address': '127.0.0.1:443'
        'certificates':
          - 'certificate': './test/cert.crt'
            'key': './test/cert.key'

  • safe_browsing: The optional safe browsing web server configurations. Every request is responded with the content from the file to which the block_page property points.

    See the full description of this API on the HTTP API page.

    Property bind has the same format as non_doh_bind below. The addresses should be different from the adult_blocking server, and the same as the ones of the block_host property in the safe_browsing and adult_blocking objects correspondingly.

    While this object is optional, both bind and block_page properties within them are required.

    Property examples:

    'safe_browsing':
  'bind':
    - 'address': '127.0.0.1:80'
    - 'address': '127.0.0.1:443'
      'certificates':
        - 'certificate': './test/cert.crt'
          'key': './test/cert.key'
  'block_page': '/var/www/block_page.html'

  • adult_blocking: The optional adult blocking web server configurations. The format of the values is the same as in the safe_browsing object above.

  • non_doh_bind: The optional listen addresses and optional TLS configuration for the web service in addition to the ones in the DNS-over-HTTPS handlers. The certificates array has the same format as the one in a server group's TLS settings. In the special case of GET /robots.txt requests, a special response is served; this response could be overwritten with static content.

    Property example:

    'non_doh_bind':
  - 'address': '127.0.0.1:80'
  - 'address': '127.0.0.1:443'
    'certificates':
      - 'certificate': './test/cert.crt'
        'key': './test/cert.key'

  • static_content: The optional inline static content mapping. Not served on the linked_ip, safe_browsing and adult_blocking servers. Paths must not duplicate the ones used by the DNS-over-HTTPS server.

    Property example:

    'static_content':
    '/favicon.ico':
        'content_type': 'image/x-icon'
        'content': 'base64content'

  • root_redirect_url: The optional URL to which non-DNS and non-Debug HTTP requests are redirected. If not set, AdGuard DNS will respond with a 404 status to all such requests.

    Example: https://adguard-dns.com/.

  • error_404 and error_500: The optional paths to the 404 page and the 500 page HTML files correspondingly. If not set, a simple plain text 404 or 500 page is served.

    Example: /var/www/404.html.

  • timeout: The timeout for server operations, as a human-readable duration.

    Example: 30s.

Safe Browsing

The safe_browsing object has the following properties:

  • block_host: The host with which to respond to any requests that match the filter.

    Example: standard-block.dns.adguard.com.

  • cache_size: The size of the response cache, in entries.

    WARNING: CURRENTLY IGNORED! See AGDNS-398.

    Example: 1024.

  • cache_ttl: The TTL of the response cache, as a human-readable duration.

    Example: 1h.

  • url: The URL from which the contents can be updated. The URL must reply with a 200 status code.

    Example: https://example.com/safe_browsing.txt.

  • refresh_interval: How often AdGuard DNS refreshes the filter.

    Example: 1m.

Adult Content Blocking

The adult_blocking object has the same properties as the safe_browsing one above.

Filter Lists

The filters object has the following properties:

  • response_ttl: The default TTL to set for responses to queries for blocked or modified domains, as a human-readable duration. It is used for anonymous users. For users with profiles, the TTL from their profile settings are used.

    Example: 10s.

  • custom_filter_cache_size: The size of the LRU cache of compiled filtering rule engines for profiles with custom filtering rules, in entries. Zero means no caching, which slows down queries.

    Example: 1024.

  • refresh_interval: How often AdGuard DNS refreshes the rule-list filters from the filter index, as well as the blocked services list from the [blocked list index][env-blocked_services)].

    Example: 1h.

  • refresh_timeout: The timeout for the entire filter update operation, as a human-readable duration. Be aware that each individual refresh operation also has its own hardcoded 30s timeout.

    Example: 5m.

Filtering Groups

The items of the filtering_groups array have the following properties:

  • id: The unique ID of this filtering group.

    Example: default.

  • rule_lists: Filtering rule lists settings. This object has the following properties:

    • enabled: Shows if rule-list filtering should be enforced. If it is set to false, the rest of the settings are ignored.

      Example: true.

    • ids: The array of rule-list IDs used in this filtering group.

      Example: [adguard_dns_default].

  • parental: Parental protection settings. This object has the following properties:

    • enabled: Shows if any kind of parental protection filtering should be enforced at all. If it is set to false, the rest of the settings are ignored.

      Example: true.

    • block_adult: If true, adult content blocking is enabled for this filtering group by default. Requires enabled to also be true.

      Example: true.

    • general_safe_search: If true, general safe search is enabled for this filtering group by default. Requires enabled to also be true.

      Example: true.

    • youtube_safe_search: If true, YouTube safe search is enabled for this filtering group by default. Requires enabled to also be true.

      Example: true.

  • safe_browsing: General safe browsing settings. This object has the following properties:

    • enabled: Shows if the general safe browsing filtering should be enforced. If it is set to false, the rest of the settings are ignored.

      Example: true.

  • private_relay: If true, Apple Private Relay queries are blocked for requests using this filtering group.

    Example: false.

Server Groups

The items of the server_groups array have the following properties:

  • name: The unique name of this server group.

    Example: adguard_dns_default.

  • filtering_group: The default filtering group for this server group. It is used for anonymous users.

    Example: default.

  • tls: The optional TLS configuration object. See below.

  • ddr: The DDR configuration object. See below.

  • servers: Server configuration for this filtering group. See below.

TLS

  • certificates: The array of objects with paths to the certificate and the private key for this server group.

    Property example:

    'certificates':
  - 'certificate': '/etc/dns/cert.crt'
    'key': '/etc/dns/cert.key'

  • session_keys: The array of file paths from which the each server's TLS session keys are updated. Session ticket key files must contain at least 32 bytes.

    Property example:

    'session_keys':
  - './private/key_1'
  - './private/key_2'

  • device_id_wildcards: The array of domain name wildcards to use to detect clients' device IDs. Use this to prevent conflicts when using certificates for subdomains.

    Property example:

    'device_id_wildcards':
  - '*.d.dns.example.com'

DDR

The DDR configuration object. Many of these data duplicate data from objects in the servers array. This was done because there was an opinion that a more restrictive configuration that automatically collected the required data was not self-describing and flexible enough.

  • enabled: Shows if DDR queries are processed. If it is set to false, DDR domain name queries receive an NXDOMAIN response.

    Example: true.

  • device_records: The device ID wildcard to record template mapping. The keys should generally be kept in sync with the device_id_wildcards field of the tls object.

    The values have the following properties:

    • doh_path: The path template for the DoH DDR SVCB records. It is optional, unless https_port below is set.

    • https_port: The optional port to use in DDR responses about the DoH resolver. If it is zero, the DoH resolver address is not included into the answer. A non-zero https_port should not be the same as tls_port below.

    • quic_port: The optional port to use in DDR responses about the DoQ resolver. If it is zero, the DoQ resolver address is not included into the answer.

    • tls_port: The optional port to use in DDR responses about the DoT resolver. If it is zero, the DoT resolver address is not included into the answer. A non-zero tls_port should not be the same as https_port above.

    • ipv4_hints: The optional hints about the IPv4-addresses of the server.

    • ipv6_hints: The optional hints about the IPv6-addresses of the server.

    Property example:

    'device_records':
    '*.d.dns.example.com':
        doh_path: '/dns-query{?dns}'
        https_port: 443
        quic_port: 853
        tls_port: 853
        ipv4_hints:
          - 1.2.3.4
        ipv6_hints:
          - '2001::1234'
    '*.e.dns.example.org':
        doh_path: '/dns-query{?dns}'
        https_port: 10443
        quic_port: 10853
        tls_port: 10853
        ipv4_hints:
          - 5.6.7.8
        ipv6_hints:
          - '2001::5678'

  • public_records: The public domain name to DDR record template mapping. The format of the values is the same as in the device_records above.

Servers

The items of the servers array have the following properties:

  • name: The unique name of this server.

    Example: default_dns.

  • protocol: The protocol to use on this server. The following values are supported:

    • dns
    • dnscrypt
    • https
    • quic
    • tls

    Example: dns.

  • linked_ip_enabled: If true, use the profiles' linked IPs to detect.

    Default: false.

    Example: true.

  • bind_addresses: The array of ip:port addresses to listen on.

    Example: [127.0.0.1:53, 192.168.1.1:53].

  • dnscrypt: The optional DNSCrypt configuration object. It has the following properties:

    • config_path: The path to the DNSCrypt configuration file. See the configuration section of the DNSCrypt module.

      Must not be set if inline is set.

      Example: /etc/dns/dnscrypt.yml

    • inline: The DNSCrypt configuration, inline. See the configuration section of the DNSCrypt module.

      Must not be set if config_path is set.

      Property example:

      'inline':
  'provider_name': '2.dnscrypt-cert.example.org'
  'public_key': 'F11DDBCC4817E543845FDDD4CB881849B64226F3DE397625669D87B919BC4FB0'
  'private_key': '5752095FFA56D963569951AFE70FE1690F378D13D8AD6F8054DFAA100907F8B6F11DDBCC4817E543845FDDD4CB881849B64226F3DE397625669D87B919BC4FB0'
  'resolver_secret': '9E46E79FEB3AB3D45F4EB3EA957DEAF5D9639A0179F1850AFABA7E58F87C74C4'
  'resolver_public': '9327C5E64783E19C339BD6B680A56DB85521CC6E4E0CA5DF5274E2D3CE026C6B'
  'es_version': 1
  'certificate_ttl': 8760h

Connectivity Check

The connectivity_check object has the following properties:

  • probe_ipv4: The IPv4 address with port to which a connectivity check is performed.

    Example: 8.8.8.8:53.

  • probe_ipv6: The optional IPv6 address with port to which a connectivity check is performed. This field is required in case of any IPv6 address in bind_addresses.

    Example: [2001:4860:4860::8888]:53.

Additional Metrics Info

The additional_metrics_info object is a map of strings with extra information which is exposed by dns_app_additional_info metric.

Map keys must match reqular expression ^[a-zA-Z_][a-zA-Z0-9_]*$. See Prometheus documentation on valid labels.

Property example:

'additional_metrics_info':
    'info_key_1': 'info_value_1'
    'info_key_2': 'info_value_2'

The Prometheus metrics key is additional_info. For example:

# HELP dns_app_additional_info A metric with a constant '1' value labeled by additional info provided in configuration
# TYPE dns_app_additional_info gauge
dns_app_additional_info{info_key_1="info_value_1",info_key_2="info_value_2"} 1