# Settings: Set DNS Settings
## Endpoint
`/api/settings/set`
**Obsolete Path:** `/api/setDnsSettings`
## Method
GET or POST
## Description
Changes DNS server settings. Any parameter passed will **overwrite** the existing value for that parameter. To append values, first call Get DNS Settings, append, then pass the updated value. Can also accept settings as JSON POST body in the same format returned by Get DNS Settings.
## Authentication
Required. Token must have **Settings: Modify** permission.
## Parameters
| `token` | string | Yes | No | Session token from `login` or `createToken`. |
| `dnsServerDomain` | string | No | No | Primary domain name used by the DNS server to identify itself. |
| `dnsServerLocalEndPoints` | string | No | No | Comma-separated list of IP:port pairs for the DNS server to listen on. |
| `dnsServerIPv4SourceAddresses` | string | No | No | Comma-separated IPv4 source addresses for outbound DNS requests. Network addresses accepted. |
| `dnsServerIPv6SourceAddresses` | string | No | No | Comma-separated IPv6 source addresses for outbound DNS requests. Only used when `preferIPv6` is enabled. |
| `defaultRecordTtl` | integer | No | No | Default TTL for new records. Cluster parameter. |
| `defaultNsRecordTtl` | integer | No | No | Default TTL for NS records in primary zones. Cluster parameter. |
| `defaultSoaRecordTtl` | integer | No | No | Default TTL for SOA records in primary zones. Cluster parameter. |
| `defaultResponsiblePerson` | string | No | No | Default SOA responsible person email. Cluster parameter. |
| `useSoaSerialDateScheme` | bool | No | No | Default SOA serial option for new primary zones. Cluster parameter. |
| `minSoaRefresh` | integer | No | No | Minimum SOA Refresh interval for secondary/stub zones. Initial: `300`. Cluster parameter. |
| `minSoaRetry` | integer | No | No | Minimum SOA Retry interval for secondary/stub zones. Initial: `300`. Cluster parameter. |
| `zoneTransferAllowedNetworks` | string | No | No | Comma-separated IPs/networks allowed zone transfer without TSIG. Cluster parameter. |
| `notifyAllowedNetworks` | string | No | No | Comma-separated IPs/networks allowed to notify secondary zones. Cluster parameter. |
| `dnsAppsEnableAutomaticUpdate` | bool | No | No | Allow DNS server to auto-update DNS apps from the store (checks every 24h). Cluster parameter. |
| `preferIPv6` | bool | No | No | Use IPv6 for querying when possible. Initial: `false`. |
| `enableUdpSocketPool` | bool | No | No | Enable UDP socket pool for outbound DNS-over-UDP requests. |
| `socketPoolExcludedPorts` | string | No | No | Comma-separated port numbers excluded from UDP socket pool. |
| `udpPayloadSize` | integer | No | No | Max EDNS UDP payload size. Range: 512-4096. Initial: `1232`. Cluster parameter. |
| `dnssecValidation` | bool | No | No | Enable DNSSEC validation of responses. Cluster parameter. |
| `eDnsClientSubnet` | bool | No | No | Enable EDNS Client Subnet. Cluster parameter. |
| `eDnsClientSubnetIPv4PrefixLength` | integer | No | No | ECS IPv4 prefix length. Initial: `24`. Cluster parameter. |
| `eDnsClientSubnetIPv6PrefixLength` | integer | No | No | ECS IPv6 prefix length. Initial: `56`. Cluster parameter. |
| `eDnsClientSubnetIpv4Override` | string | No | No | IPv4 network address override for ECS. Cluster parameter. |
| `eDnsClientSubnetIpv6Override` | string | No | No | IPv6 network address override for ECS. Cluster parameter. |
| `qpmPrefixLimitsIPv4` | string | No | No | Pipe-separated rows of `prefix,udpLimit,tcpLimit`. Set to `false` to remove all entries. Cluster parameter. |
| `qpmPrefixLimitsIPv6` | string | No | No | Pipe-separated rows of `prefix,udpLimit,tcpLimit`. Set to `false` to remove all entries. Cluster parameter. |
| `qpmLimitSampleMinutes` | integer | No | No | QPM limit sample size in minutes. Initial: `5`. Cluster parameter. |
| `qpmLimitUdpTruncationPercentage` | integer | No | No | Percentage of UDP requests truncated when QPM exceeded. Range: 0-100. Initial: `50`. Cluster parameter. |
| `qpmLimitBypassList` | string | No | No | Comma-separated IPs/networks that bypass QPM limits. Cluster parameter. |
| `clientTimeout` | integer | No | No | Timeout (ms) before ServerFailure to clients. Range: 1000-10000. Initial: `4000`. Cluster parameter. |
| `tcpSendTimeout` | integer | No | No | TCP send timeout (ms). Range: 1000-90000. Initial: `10000`. Cluster parameter. |
| `tcpReceiveTimeout` | integer | No | No | TCP receive timeout (ms). Range: 1000-90000. Initial: `10000`. Cluster parameter. |
| `quicIdleTimeout` | integer | No | No | QUIC idle timeout (ms). Range: 1000-90000. Initial: `60000`. Cluster parameter. |
| `quicMaxInboundStreams` | integer | No | No | Max inbound QUIC streams per connection. Range: 1-1000. Initial: `100`. Cluster parameter. |
| `listenBacklog` | integer | No | No | Max pending inbound connections. Initial: `100`. Cluster parameter. |
| `maxConcurrentResolutionsPerCore` | integer | No | No | Max concurrent async outbound resolutions per CPU core. Initial: `100`. Cluster parameter. |
| `webServiceLocalAddresses` | string | No | No | Comma-separated web service listen addresses. |
| `webServiceHttpPort` | integer | No | No | Web service HTTP port. Initial: `5380`. |
| `webServiceEnableTls` | bool | No | No | Enable HTTPS for web service. |
| `webServiceEnableHttp3` | bool | No | No | Enable HTTP/3 for web service. |
| `webServiceHttpToTlsRedirect` | bool | No | No | Enable HTTP to HTTPS redirect. |
| `webServiceTlsPort` | integer | No | No | Web service HTTPS port. |
| `webServiceUseSelfSignedTlsCertificate` | bool | No | No | Use auto-generated self-signed cert when no cert path specified. |
| `webServiceTlsCertificatePath` | string | No | No | Path to PKCS#12 (.pfx) certificate with private key for web service HTTPS. |
| `webServiceTlsCertificatePassword` | string | No | No | Certificate password, if any. |
| `webServiceRealIpHeader` | string | No | No | HTTP header for client real IP from reverse proxy. |
| `enableDnsOverUdpProxy` | bool | No | No | Enable DNS-over-UDP-PROXY (PROXY Protocol v1 & v2). Configure `reverseProxyNetworkACL`. |
| `enableDnsOverTcpProxy` | bool | No | No | Enable DNS-over-TCP-PROXY (PROXY Protocol v1 & v2). Configure `reverseProxyNetworkACL`. |
| `enableDnsOverHttp` | bool | No | No | Enable DNS-over-HTTP. Must be used with TLS terminating reverse proxy. Configure `reverseProxyNetworkACL`. Also enables HTTP challenge for HTTPS cert renewal. |
| `enableDnsOverTls` | bool | No | No | Enable DNS-over-TLS. |
| `enableDnsOverHttps` | bool | No | No | Enable DNS-over-HTTPS. |
| `enableDnsOverQuic` | bool | No | No | Enable DNS-over-QUIC. |
| `dnsOverUdpProxyPort` | integer | No | No | DNS-over-UDP-PROXY port. Initial: `538`. |
| `dnsOverTcpProxyPort` | integer | No | No | DNS-over-TCP-PROXY port. Initial: `538`. |
| `dnsOverHttpPort` | integer | No | No | DNS-over-HTTP port. Initial: `80`. |
| `dnsOverTlsPort` | integer | No | No | DNS-over-TLS port. Initial: `853`. |
| `dnsOverHttpsPort` | integer | No | No | DNS-over-HTTPS port. Initial: `443`. |
| `dnsOverQuicPort` | integer | No | No | DNS-over-QUIC port. Initial: `853`. |
| `reverseProxyNetworkACL` | string | No | No | ACL for reverse proxy access. Enter IPs/networks one per entry. Prefix with `!` to deny. Processed in order; default deny all. |
| `dnsTlsCertificatePath` | string | No | No | Path to PKCS#12 (.pfx) certificate for DNS-over-TLS and DNS-over-HTTPS. |
| `dnsTlsCertificatePassword` | string | No | No | DNS TLS certificate password, if any. |
| `dnsOverHttpRealIpHeader` | string | No | No | HTTP header for client real IP for DNS-over-HTTP. |
| `tsigKeys` | string | No | No | Pipe-separated rows of `keyName,sharedSecret,algorithmName`. Set to `false` to remove all keys. Supported algorithms: `hmac-md5.sig-alg.reg.int`, `hmac-sha1`, `hmac-sha256`, `hmac-sha256-128`, `hmac-sha384`, `hmac-sha384-192`, `hmac-sha512`, `hmac-sha512-256`. Cluster parameter. |
| `recursion` | string | No | No | Recursion policy. Valid: [`Deny`, `Allow`, `AllowOnlyForPrivateNetworks`, `UseSpecifiedNetworkACL`]. Cluster parameter. |
| `recursionNetworkACL` | string | No | No | Comma-separated ACL for recursion. Prefix with `!` to deny. Default denies all except loopback. Set to `false` to clear. Only used when `recursion` = `UseSpecifiedNetworkACL`. Cluster parameter. |
| `randomizeName` | bool | No | No | Enable QNAME randomization (draft-vixie-dnsext-dns0x20-00) for UDP. Initial: `true`. Cluster parameter. |
| `qnameMinimization` | bool | No | No | Enable QNAME minimization (draft-ietf-dnsop-rfc7816bis-04). Initial: `true`. Cluster parameter. |
| `resolverRetries` | integer | No | No | Recursive resolver retry count. Cluster parameter. |
| `resolverTimeout` | integer | No | No | Recursive resolver timeout (ms). Cluster parameter. |
| `resolverConcurrency` | integer | No | No | Recursive resolver concurrent request count. Cluster parameter. |
| `resolverMaxStackCount` | integer | No | No | Recursive resolver max stack count. Cluster parameter. |
| `saveCache` | bool | No | No | Save DNS cache to disk when server stops. |
| `serveStale` | bool | No | No | Enable serve stale for expired cache records. Initial: `true`. |
| `serveStaleTtl` | integer | No | No | TTL (seconds) for stale cached records. Recommended: 1-3 days. Max: 7 days. Initial: `259200`. |
| `serveStaleAnswerTtl` | integer | No | No | TTL (seconds) for stale response records. Range: 0-300. Recommended: `30`. |
| `serveStaleResetTtl` | integer | No | No | TTL (seconds) to reset stale record TTL on refresh failure. Range: 10-900. Recommended: `30`. |
| `serveStaleMaxWaitTime` | integer | No | No | Max wait (ms) before serving stale. Range: 0-1800. Default: `1800`. Setting 0 returns stale immediately. |
| `cacheMinimumRecordTtl` | integer | No | No | Minimum record TTL in cache. Initial: `10`. |
| `cacheMaximumRecordTtl` | integer | No | No | Maximum record TTL in cache. Initial: `86400`. |
| `cacheNegativeRecordTtl` | integer | No | No | Negative record TTL when no SOA MINIMUM. Initial: `300`. |
| `cacheFailureRecordTtl` | integer | No | No | Failure response cache TTL. Initial: `60`. |
| `cachePrefetchEligibility` | integer | No | No | Min initial TTL for prefetch eligibility. |
| `cachePrefetchTrigger` | integer | No | No | TTL threshold triggering immediate prefetch. Set `0` to disable prefetching and auto-prefetching. |
| `cachePrefetchSampleIntervalInMinutes` | integer | No | No | Auto-prefetch sampling interval (minutes). |
| `cachePrefetchSampleEligibilityHitsPerHour` | integer | No | No | Min hits/hour for auto-prefetch eligibility. |
| `enableBlocking` | bool | No | No | Enable domain blocking via Blocked Zone and Block List Zone. Cluster parameter. |
| `allowTxtBlockingReport` | bool | No | No | Respond with TXT blocking reports for TXT requests. Cluster parameter. |
| `blockingBypassList` | string | No | No | Comma-separated IPs/networks that bypass blocking. Cluster parameter. |
| `blockingType` | string | No | No | Blocking response type. Valid: [`AnyAddress`, `NxDomain`, `CustomAddress`]. `AnyAddress` responds with `0.0.0.0` and `::`. Cluster parameter. |
| `blockingAnswerTtl` | integer | No | No | TTL (seconds) for blocking responses. Cluster parameter. |
| `customBlockingAddresses` | string | No | No | Comma-separated IPs for blocked domain responses. Only used when `blockingType` = `CustomAddress`. Cluster parameter. |
| `blockListUrls` | string | No | No | Comma-separated block list URLs. Server auto-downloads and updates. Expected format: hosts file or plain domain list. Set to `false` to remove. Cluster parameter. |
| `blockListUpdateIntervalHours` | integer | No | No | Block list update interval (hours). Initial: `24`. Cluster parameter. |
| `proxyType` | string | No | No | Proxy type. Valid: [`None`, `Http`, `Socks5`]. Cluster parameter. |
| `proxyAddress` | string | No | No | Proxy server hostname or IP. Cluster parameter. |
| `proxyPort` | integer | No | No | Proxy server port. Cluster parameter. |
| `proxyUsername` | string | No | No | Proxy server username. Cluster parameter. |
| `proxyPassword` | string | No | No | Proxy server password. Cluster parameter. |
| `proxyBypass` | string | No | No | Comma-separated bypass list (IPs, CIDRs, hostnames). Cluster parameter. |
| `forwarders` | string | No | No | Comma-separated forwarder addresses. Set to `false` to remove forwarders (DNS server does recursive resolution). Cluster parameter. |
| `forwarderProtocol` | string | No | No | Forwarder transport protocol. Valid: [`Udp`, `Tcp`, `Tls`, `Https`, `Quic`]. Cluster parameter. |
| `concurrentForwarding` | bool | No | No | Query multiple forwarders concurrently, selecting fastest. Cluster parameter. |
| `forwarderRetries` | integer | No | No | Forwarder retry count. Cluster parameter. |
| `forwarderTimeout` | integer | No | No | Forwarder timeout (ms). Cluster parameter. |
| `forwarderConcurrency` | integer | No | No | Forwarder concurrent request count. Cluster parameter. |
| `loggingType` | string | No | No | Log output type. Valid: [`None`, `File`, `Console`, `FileAndConsole`]. Initial: `File`. |
| `enableLogging` | bool | No | No | Enable error/audit logging. Initial: `true`. **Obsolete** -- use `loggingType` instead. |
| `ignoreResolverLogs` | bool | No | No | Stop logging domain resolution errors. |
| `logQueries` | bool | No | No | Log every query and response. Initial: `false`. |
| `useLocalTime` | bool | No | No | Use local time instead of UTC for logging. Initial: `false`. |
| `logFolder` | string | No | No | Log file folder path (can be relative to config folder). Initial: `logs`. |
| `maxLogFileDays` | integer | No | No | Max days to retain log files. `0` disables auto-delete. Recommended: `365`. |
| `enableInMemoryStats` | bool | No | No | Enable in-memory stats only (only Last Hour on Dashboard, no disk storage). |
| `maxStatFileDays` | integer | No | No | Max days to retain stat files. `0` disables auto-delete. Recommended: `365`. |
## Response Fields
Returns the newly updated settings in the same format as the Get DNS Settings response. See `settings_get.md` for the full response schema.
## Conditional Logic Notes
- **Overwrite semantics**: Every parameter passed **overwrites** the existing value. To append, read first with Get DNS Settings, merge, then set.
- **Cluster parameters**: Parameters marked as "Cluster parameter" are automatically synced across all cluster nodes when Clustering is initialized.
- **`recursionNetworkACL`**: Only effective when `recursion` is set to `UseSpecifiedNetworkACL`.
- **`customBlockingAddresses`**: Only effective when `blockingType` is set to `CustomAddress`.
- **`dnsServerIPv6SourceAddresses`**: Only used when `preferIPv6` is enabled.
- **`enableDnsOverUdpProxy`/`enableDnsOverTcpProxy`/`enableDnsOverHttp`**: Should be paired with `reverseProxyNetworkACL` configuration.
- **`enableLogging`**: Obsolete in favor of `loggingType`.
- **`blockListUrls`/`forwarders`/`recursionNetworkACL`/`qpmPrefixLimitsIPv4`/`qpmPrefixLimitsIPv6`/`tsigKeys`**: Can be set to `false` (string) to remove all existing values.
- **JSON POST alternative**: Instead of query parameters, settings can be POSTed as JSON in the same format returned by Get DNS Settings.
## Edge Cases
- Setting `cachePrefetchTrigger` to `0` disables both prefetching and auto-prefetching.
- Setting `serveStaleMaxWaitTime` to `0` causes immediate stale answers without waiting for upstream.
- The `proxyType`, `proxyAddress`, `proxyPort` etc. are independent parameters -- setting `proxyType` to `None` does not clear the other proxy fields.
- `forwarders` set to the string `false` removes forwarders; an empty string may behave differently.
- `enableDnsOverHttp` has a side effect: it also enables HTTP challenge (webroot) for automatic TLS certificate renewal for DNS-over-HTTPS.