AdGuardDNS/doc/externalhttp.md

AdGuard DNS external HTTP API requirements

AdGuard DNS uses information from external HTTP APIs for filtering and other pieces of its functionality. Whenever it makes requests to these services, AdGuard DNS sets the User-Agent header. All services described in this document should set the Server header in their replies.

Contents

• Backend billing statistics
• Backend DNSCheck service
• Backend profiles service
• Backend ratelimit service
• Consul key-value storage
• Filtering
  • Blocked services
  • Filtering rule lists
  • Safe search
• Proxied linked IP and dynamic DNS (DDNS) Endpoints
• Rule statistics service

Backend billing statistics

This is the service to which the BILLSTAT_URL environment variable points. Supports gRPC(s) URLs. The service must correspond to ./internal/backendpb/dns.proto.

This service is disabled when all server groups have property profiles_enabled set to false.

Backend DNSCheck service

This is the service to which the DNSCHECK_REMOTEKV_URL environment variable points. Supports gRPC(s) URLs. The service must correspond to ./internal/backendpb/dns.proto.

This service is only enabled when the check.kv object has the type property set to backend.

Backend profiles service

This is the service to which the PROFILES_URL environment variable points. Supports gRPC(s) URLs. The service must correspond to ./internal/backendpb/dns.proto.

This service is disabled when all server groups have property profiles_enabled set to false.

Backend ratelimit_service

This is the service to which the BACKEND_RATELIMIT_URL environment variable points. Supports gRPC(s) URLs. The service must correspond to ./internal/backendpb/dns.proto.

This service is only enabled when the ratelimit object has the type property set to backend.

Consul key-value storage

A Consul service can be used for the DNS server check and dynamic rate-limit allowlist features. Currently used endpoints can be seen in the documentation of the CONSUL_ALLOWLIST_URL, CONSUL_DNSCHECK_KV_URL, and CONSUL_DNSCHECK_SESSION_URL environment variables.

The CONSUL_ALLOWLIST_URL endpoint must respond with a 200 OK response code and a JSON document in the following format:

[
  {
    "Address": "1.2.3.4"
  }
]

TODO(a.garipov): Add examples of other responses.

Filtering

Blocked services

This endpoint, defined by BLOCKED_SERVICE_INDEX_URL, must respond with a 200 OK response code and a JSON document in the following format:

{
  "blocked_services": [
    {
      "id": "my_filter",
      "rules": [
        "||example.com^",
        "||example.net^"
      ]
    }
  ]
}

All properties must be filled with valid IDs and rules. Additional fields in objects are ignored.

Filtering rule lists

This endpoint, defined by FILTER_INDEX_URL, must respond with a 200 OK response code and a JSON document in the following format:

{
  "filters": [
    {
      "filterKey": "my_filter",
      "downloadUrl": "https://cdn.example.com/assets/my_filter.txt"
    }
  ]
}

All properties must be filled with valid IDs and URLs. Additional fields in objects are ignored.

Safe search

These endpoints, defined by GENERAL_SAFE_SEARCH_URL and YOUTUBE_SAFE_SEARCH_URL, must respond with a 200 OK response code and filtering rule lists with $dnsrewrite rules for A, AAAA, or CNAME types. For example, for YouTube:

|m.youtube.com^$dnsrewrite=NOERROR;CNAME;restrictmoderate.youtube.com
|www.youtube-nocookie.com^$dnsrewrite=NOERROR;CNAME;restrictmoderate.youtube.com
|www.youtube.com^$dnsrewrite=NOERROR;CNAME;restrictmoderate.youtube.com
|youtube.googleapis.com^$dnsrewrite=NOERROR;CNAME;restrictmoderate.youtube.com
|youtubei.googleapis.com^$dnsrewrite=NOERROR;CNAME;restrictmoderate.youtube.com

Proxied linked iP and dynamic DNS (DDNS) endpoints

The service defined by the LINKED_IP_TARGET_URL environment variable should define the following endpoints:

• GET /linkip/{device_id}/{encrypted}/status
• GET /linkip/{device_id}/{encrypted}
• POST /ddns/{device_id}/{encrypted}/{domain}
• POST /linkip/{device_id}/{encrypted}

The AdGuard DNS proxy will add the X-Connecting-Ip header with the IP address of the original client as well as set the User-Agent header to its own value.

Rule statistics service

This endpoint, defined by RULESTAT_URL, must respond with a 200 OK response code and accept a JSON document in the following format:

{
  "filters": [
    {
      "15": {
        "||example.com^": 1234,
        "||example.net^": 5678
      }
    }
  ]
}

The objects may include new properties in the future.