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.

Backend Billing Statistics
Backend Profiles Service
Consul Key-Value Storage
Filtering
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 http(s): and grpc(s) URLs. In case of GRPC protocol, the service must correspond to ./internal/backendpb/backend.proto. In case of HTTP protocol this service must provide one endpoint: POST /dns_api/v1/devices_activity, it must respond with a 200 OK response code and accept a JSON document in the following format:

{
  "devices": [
    {
      "client_country": "AU",
      "device_id": "abcd1234",
      "time_ms": 1624443079309,
      "asn": 1234,
      "queries": 1000,
      "proto": 1
    }
  ]
}

Backend Profiles Service

This is the service to which the PROFILES_URL environment variable points. Supports http(s): and grpc(s) URLs. In case of GRPC protocol, the service must correspond to ./internal/backendpb/backend.proto. In case of HTTP protocol this service must provide one endpoint: GET /dns_api/v1/settings, it must respond with a 200 OK response code and accept a JSON document in the following format:

{
  "sync_time": 1624443079309,
  "settings": [
    {
      "dns_id": "83f3ea8f",
      "filtering_enabled": true,
      "query_log_enabled": true,
      "safe_browsing":
      {
        "enabled": true
      },
      "deleted": true,
      "block_private_relay": false,
      "devices": [
        {
          "id": "0d7724fa",
          "name": "Device 1",
          "filtering_enabled": true,
          "linked_ip": "1.2.3.4"
        }
      ],
      "parental": {
        "enabled": false,
        "block_adult": false,
        "general_safe_search": false,
        "youtube_safe_search": false,
        "blocked_services": [
          "youtube"
        ],
        "schedule": {
          "tmz": "GMT",
          "mon": [
            "0s",
            "59m"
          ],
          "tue": [
            "0s",
            "59m"
          ],
          "wed": [
            "0s",
            "59m"
          ],
          "thu": [
            "0s",
            "59m"
          ],
          "fri": [
            "0s",
            "59m"
          ]
        }
      },
      "rule_lists": {
        "enabled": true,
        "ids": [
          "1"
        ]
      },
      "filtered_response_ttl": 3600,
      "custom_rules": [
        "||example.org^"
      ]
    }
  ]
}

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": [
    {
      "downloadUrl": "https://cdn.example.com/assets/my_filter.txt",
      "id": "my_filter"
    }
  ]
}

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 CF-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.

7.8 KiB Raw Blame History

AdGuard DNS External HTTP API Requirements

Contents

7.8 KiB

Raw Blame History