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 And Linked IP Service
Consul Key-Value Storage
Filtering
Rule Statistics Service

Backend And Linked IP Service

This is the service to which the BACKEND_ENDPOINT environment variable points. This service must provide two endpoints:

`GET /dns_api/v1/settings`

This endpoint must respond with a 200 OK response code and 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^"
      ]
    }
  ]
}

`POST /dns_api/v1/devices_activity`

This endpoint 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
    }
  ]
}

Proxied Linked IP and Dynamic DNS (DDNS) Endpoints

The same service defined by the BACKEND_ENDPOINT 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.

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

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.4 KiB Raw Permalink Blame History

AdGuard DNS External HTTP API Requirements

Contents

7.4 KiB

Raw Permalink Blame History