Cloudflare API | DNS Firewall › Create DNS Firewall Cluster

Maximum DNS cache TTL This setting sets an upper bound on DNS TTLs for purposes of caching between DNS Firewall and the upstream servers. Higher TTLs will be decreased to the maximum defined here for caching purposes.

minimum_cache_ttl: number

Optional

(maximum: 36000, minimum: 30, default: 60)

Minimum DNS cache TTL This setting sets a lower bound on DNS TTLs for purposes of caching between DNS Firewall and the upstream servers. Lower TTLs will be increased to the minimum defined here for caching purposes.

negative_cache_ttl: number

Optional

(maximum: 36000, minimum: 30)

Negative DNS cache TTL This setting controls how long DNS Firewall should cache negative responses (e.g., NXDOMAIN) from the upstream servers.

ratelimit: number

Optional

(maximum: 1000000000, minimum: 100)

Ratelimit in queries per second per datacenter (applies to DNS queries sent to the upstream nameservers configured on the cluster)

retries: number

Optional

(maximum: 2, minimum: 0, default: 2)

Number of retries for fetching DNS responses from upstream nameservers (not counting the initial attempt)

Response fields

errors: Array<{ code, message, documentation_url, 1 more... }>

messages: Array<{ code, message, documentation_url, 1 more... }>

success: true

Whether the API call was successful.

result: { id, deprecate_any_requests, dns_firewall_ips, 10 more... }

Optional

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/dns_firewall \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
      "name": "My Awesome DNS Firewall cluster",
      "upstream_ips": [
        "192.0.2.1",
        "198.51.100.1",
        "2001:DB8:100::CF"
      ],
      "deprecate_any_requests": true,
      "maximum_cache_ttl": 900,
      "minimum_cache_ttl": 60,
      "negative_cache_ttl": 900,
      "ratelimit": 600,
      "retries": 2
    }'

200Example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "023e105f4ecef8ad9ca31a8372d0c353",
    "deprecate_any_requests": true,
    "dns_firewall_ips": [
      "203.0.113.1",
      "203.0.113.254",
      "2001:DB8:AB::CF",
      "2001:DB8:CD::CF"
    ],
    "ecs_fallback": false,
    "maximum_cache_ttl": 900,
    "minimum_cache_ttl": 60,
    "name": "My Awesome DNS Firewall cluster",
    "negative_cache_ttl": 900,
    "ratelimit": 600,
    "retries": 2,
    "upstream_ips": [
      "192.0.2.1",
      "198.51.100.1",
      "2001:DB8:100::CF"
    ],
    "attack_mitigation": {
      "enabled": true,
      "only_when_upstream_unhealthy": false
    }
  }
}

Delete DNS Firewall Cluster -> Envelope<{ id }>

delete/accounts/{account_id}/dns_firewall/{dns_firewall_id}

Delete a DNS Firewall cluster

Update DNS Firewall Cluster -> Envelope<{ id, deprecate_any_requests, dns_firewall_ips, 10 more... }>

patch/accounts/{account_id}/dns_firewall/{dns_firewall_id}

Modify the configuration of a DNS Firewall cluster

DNS Firewall Cluster Details -> Envelope<{ id, deprecate_any_requests, dns_firewall_ips, 10 more... }>

get/accounts/{account_id}/dns_firewall/{dns_firewall_id}

Show a single DNS Firewall cluster for an account

List DNS Firewall Clusters -> V4PagePaginationArray<{ id, deprecate_any_requests, dns_firewall_ips, 10 more... }>

get/accounts/{account_id}/dns_firewall

List DNS Firewall clusters for an account

Domain types

AttackMitigation = { enabled, only_when_upstream_unhealthy }

Attack mitigation settings

FirewallIPs = string

Cloudflare-assigned DNS IPv4 address

UpstreamIPs = string

Upstream DNS Server IPv4 address

DNS Firewall

Analytics

dns_firewall.analytics

DNS Firewall Analytics

Reports

dns_firewall.analytics.reports

Methods

Table -> Envelope<

Report

get/accounts/{account_id}/dns_firewall/{dns_firewall_id}/dns_analytics/report

Retrieves a list of summarised aggregate metrics over a given time period.

See Analytics API properties for detailed information about the available query parameters.

DNS Firewall Analytics Reports

Bytimes

dns_firewall.analytics.reports.bytimes

Methods

By Time -> Envelope<

ByTime

get/accounts/{account_id}/dns_firewall/{dns_firewall_id}/dns_analytics/report/bytime

Retrieves a list of aggregate metrics grouped by time interval.

See Analytics API properties for detailed information about the available query parameters.

DNS Firewall

Reverse DNS

dns_firewall.reverse_dns

Methods

Update DNS Firewall Cluster Reverse DNS -> Envelope<{ ptr }>

patch/accounts/{account_id}/dns_firewall/{dns_firewall_id}/reverse_dns

Update reverse DNS configuration (PTR records) for a DNS Firewall cluster

Show DNS Firewall Cluster Reverse DNS -> Envelope<{ ptr }>

get/accounts/{account_id}/dns_firewall/{dns_firewall_id}/reverse_dns

Show reverse DNS configuration (PTR records) for a DNS Firewall cluster