DoH JSON Health Check

Check DNS resolver health using JSON-based DoH APIs (RFC 8427)

DoH JSON Health Check

DNS-MNS supports checking DNS resolver health using JSON-based DNS over HTTPS (DoH) APIs. This feature implements RFC 8427 (JSON-encoded DNS queries) and is particularly useful for users in Iran who need to verify if specific DoH resolvers are accessible.

What is JSON DoH?

Unlike standard DoH which uses binary DNS messages in the HTTP body (RFC 8484), JSON DoH uses JSON format for DNS queries and responses. This makes it:

• Easier to debug - Human-readable JSON format
• Cross-platform - Works with any HTTP client
• Lightweight - Simple GET requests with query parameters

Usage

Interactive Mode

From the main menu:

1. Select [3] Encrypted DNS
2. Select [5] DoH JSON Health Check
3. Enter the resolver URL (or press Enter for default)
4. Select record type (A, AAAA, MX, TXT)
5. Enter domains to check (comma-separated)

CLI Mode

# Check a single domain with default resolver
dns-mns doh-health google.com

# Check multiple domains
dns-mns doh-health google.com twitter.com github.com

# Use a custom resolver
dns-mns doh-health --resolver https://dns.google/resolve google.com

# Check IPv6 (AAAA) records
dns-mns doh-health --type AAAA google.com

# Check MX records
dns-mns doh-health --type MX gmail.com

# Output results as JSON
dns-mns doh-health google.com --json

# Disable colors (for piping)
dns-mns doh-health google.com --no-color

Default Resolver

The default resolver is https://dns.theazizi.ir/dns-query, which is designed to work well in Iran.

Record Types

Type	Value	Description
A	1	IPv4 address
AAAA	28	IPv6 address
MX	15	Mail exchange
TXT	16	Text record
CNAME	5	Canonical name

Understanding Results

Successful Query

#1 google.com ✅ Working
     Type:    A
     Latency: 45ms
     Answers:
       • 142.250.185.78 (TTL: 300)

NXDOMAIN (Domain Not Found)

#2 nonexistent.invalid ⚠️ Domain not found (NXDOMAIN)
     Type:    A
     Latency: 32ms

This means the resolver is working, but the domain doesn’t exist.

Failed Query

#3 blocked.com ❌ Failed
     Type:    A
     Latency: 5000ms
     Error:   request failed: timeout

This indicates the resolver is not accessible or blocked.

JSON Output Format

When using --json, the output includes:

{
  "resolver": "https://dns.theazizi.ir/dns-query",
  "type": "A",
  "summary": {
    "total": 3,
    "working": 2,
    "failed": 1,
    "avg_latency_ms": 38.5
  },
  "results": [
    {
      "domain": "google.com",
      "record_type": "A",
      "works": true,
      "latency_ms": 45,
      "response": {
        "Status": 0,
        "Answer": [
          {
            "name": "google.com",
            "type": 1,
            "TTL": 300,
            "data": "142.250.185.78"
          }
        ]
      }
    }
  ]
}

Alternative Resolvers

You can use any RFC 8427-compatible resolver:

Resolver	URL	Notes
Google DNS	https://dns.google/resolve	Global, reliable
Cloudflare	https://1.1.1.1/dns-query	Fast, privacy-focused
Quad9	https://9.9.9.9:5053/dns-query	Security-focused

Many popular DoH resolvers may be blocked in Iran. If the default resolver doesn’t work, try using a VPN or finding alternative resolvers.

Troubleshooting

”request failed: timeout”

• Check your internet connection
• The resolver may be blocked - try a different one
• Try using a VPN

”HTTP 403” or “HTTP 451”

• The resolver is accessible but refusing requests
• This may indicate blocking or rate limiting

Empty answers with Status 0

• The domain exists but the resolver returned no records
• The domain may be blocked at the resolver level
• Try a different resolver

Use Cases

Verify Resolver Connectivity

dns-mns doh-health google.com

Quick check if the default resolver is working.

Test Multiple Domains

dns-mns doh-health google.com twitter.com telegram.org

Check if commonly blocked domains are accessible through the resolver.

Compare Resolvers

# Test resolver A
dns-mns doh-health --resolver https://dns.theazizi.ir/dns-query google.com --json

# Test resolver B
dns-mns doh-health --resolver https://dns.google/resolve google.com --json

Compare performance and accessibility of different resolvers.

IPv6 Support Check

dns-mns doh-health --type AAAA google.com cloudflare.com

Check if IPv6 resolution is working through the resolver.

Privacy Considerations

When using a DoH resolver, the resolver operator can see your DNS queries. Choose a resolver with a privacy policy you trust. The default resolver (dns.theazizi.ir) is designed for Iranian users but you should review its privacy policy.

Technical Details

RFC 8427 Format

The tool sends HTTP GET requests with query parameters:

GET /dns-query?name=example.com&type=1 HTTP/1.1
Host: dns.example.com
Accept: application/dns-json

Response Format

{
  "Status": 0,
  "TC": false,
  "RD": true,
  "RA": true,
  "AD": false,
  "CD": false,
  "Question": [{"name": "example.com", "type": 1}],
  "Answer": [{"name": "example.com", "type": 1, "TTL": 300, "data": "93.184.216.34"}]
}

Status Codes

Code	Name	Meaning
0	NOERROR	Success
1	FORMERR	Format error
2	SERVFAIL	Server failure
3	NXDOMAIN	Non-existent domain
5	REFUSED	Query refused

Related Commands

• dns-mns test-doh - Test standard DoH/DoT providers
• dns-mns proxy - Start resilient encrypted DNS proxy
• dns-mns verify - Check for DNS poisoning/hijacking