F5BigDnsCache Reference

The F5BigDnsCache Custom Resource (CR) configuration parameters. The F5BigDnsCache is referenced by the F5BigDnsApp CR and must be created first. Each heading below represents the top-level parameter element. For example, to set the DNS Cache name, use spec.name.

spec

Parameter Description
cacheType The type for this DNS cache: transparent or net-resolver or resolver.

spec.transparent

Parameter Description
answerDefaultZones Whether to answer queries for default zones such as localhost, reverse 127.0.0.1 and ::1 or AS112: true or false (default).
localZones.name The Fully Qualified Domain Name for a localZone.
localZones.zoneType The zoneType for this localZone: deny, refuse, static, transparent (default), type-transparent or redirect.
localZones.records Array of records for this localZone.
msgCacheSize Number of bytes allocated for the message cache. The default is 1048576.
rrsetCacheSize Number of bytes allocated for the resource record set cache. The default is 10485760.
rrsetRotate Specifies which resource record set rotation method should be used on cache responses: none (default) or query-id.

spec.netResolver

Parameter Description
answerDefaultZones Whether to answer queries for default zones such as localhost, reverse 127.0.0.1 and ::1 or AS112: true or false (default).
forwardZones.forwardZone The Fully Qualified Domain Name for a Forward Zone. Use . for all domains.
forwardZones.nameServers An array of Name Servers for a Forward Zone.
forwardZones.nameServers.ipAddress The IPv4 or IPv6 address for a Name Server.
forwardZones.nameServers.port Port for a Name Server. The default is 53.
msgCacheSize Number of bytes allocated for the message cache. The default is 1048576.
nameserverCacheCount description: Maximum number of DNS nameservers to cache. The default is 166536.
nameserverTTL Time to live, in seconds, for DNS nameservers in the cache. The default is 900.
negCacheSize Number of bytes allocated for the negative cache. The default is 1048576.
randomQueryNameCase Enables resolver to randomize the case of query names: true (default) or false.
returnTruncatedWhenNoTcp Enables resolver to return a truncated response from an upstream DNS nameserver when useTcp is set to false: The default value is false.
rrsetCacheSize Number of bytes allocated for the resource record set cache. The default is 10485760.
useIpv4 Enables the resolver to issue IPv4 queries: true (default) or false.
useIpv6 Enables the resolver to issue IPv6 queries: true (default) or false.
useTcp Enables the resolver to issue tcp queries: true (default) or false.
useUdp Enables the resolver to issue udp queries: true (default) or false.

spec.resolver

Parameter Description
answerDefaultZones Whether to answer queries for default zones such as localhost, reverse 127.0.0.1 and ::1 or AS112: true or false (default).
forwardZones.forwardZone The Fully Qualified Domain Name for a Forward Zone. Use . for all domains.
forwardZones.nameServers An array of Name Servers for a Forward Zone.
forwardZones.nameServers.ipAddress The IPv4 or IPv6 address for a Name Server.
forwardZones.nameServers.port Port for a Name Server. The default is 53.
localZones.name The Fully Qualified Domain Name for a localZone.
localZones.zoneType The zoneType for this localZone: deny, refuse, static, transparent (default), type-transparent or redirect.
localZones.records Array of records for this localZone.
maxConcurrentQueries Specifies the maximum number of concurrent distinct queries used by the resolver. A query is identified by query name, type and class. If the number of distinct queries exceeds this limit, the resolver replaces the earliest query in the queue with the new query if it has been in the queue longer than the allowed time. The default is 1024.
maxConcurrentTcp Specifies the maximum number of concurrent TCP flows used by the resolver. The default is 20.
maxConcurrentUdp Specifies the maximum number of concurrent UDP flows used by the resolver. The default is 8192.
msgCacheSize Number of bytes allocated for the message cache. The default is 1048576.
nameserverCacheCount description: Maximum number of DNS nameservers to cache. The default is 166536.
nameserverTTL Time to live, in seconds, for DNS nameservers in the cache. The default is 900.
randomQueryNameCase Enables resolver to randomize the case of query names: true (default) or false.
rootHints Specifies the IP addresses of DNS servers that the BIG-IP system considers authoritative for the DNS root nameservers. Important:By default, the BIG-IP system uses the DNS root nameservers published by InterNIC. Caution:When you add DNS root nameservers, the BIG-IP system no longer uses the default nameservers published by InterNIC, but instead uses the nameservers you add as authoritative for the DNS root nameservers.
rrsetCacheSize Specifies the number of bytes allocated for the resource record set cache. The default is 10485760.
rrsetRotate Select which resource record set rotation method should be used on cache responses: none (default) or query-id.
unwantedQueryReplyThreshold The system always rejects unsolicited replies. The default value of "0" (off) indicates the system does not generate SNMP traps or log messages when rejecting unsolicited replies. The default is 0.
useIpv4 Enables the resolver to issue IPv4 queries: true (default) or false.
useIpv6 Enables the resolver to issue IPv6 queries: true (default) or false.
useTcp Enables the resolver to issue tcp queries: true (default) or false.
useUdp Enables the resolver to issue udp queries: true (default) or false.

cacheType setting

By caching DNS responses and answering queries from the cache, the BIG-IP system is able to immediately respond to subsequent client requests for the same resource. This enhances DNS performance in two significant ways. First, answering a DNS query from the cache is faster and has a very short latency, because the sooner a client gets a DNS response, the faster the client can access the Internet resource. Secondly, caching DNS responses reduces the number of queries that have to be resolved. The BIG-IP system uses the cache to resolve the same query from multiple clients handling many more queries per second than a typical DNS resolver.

Currently, only the Transparent, Net Resolver and Resolver cache types are supported.

Cache Type Description
Transparent Cache A transparent cache does not perform recursive resolution, but instead relies on another DNS resource for resolution.
Net Resolver Cache A net-resolver cache is utilized by RESOLVER::name_lookup iRule and other non-DNS features of the Big-IP system.
Resolver Cache A resolver cache performs recursive resolution to fill its cache.

Forward Zones

Applicable only to the DNS Resolver and Net Resolver. A forward zone contains a zone name and a list of IP addresses to upstream DNS nameservers capable of answering queries for the specified zone.

Forward Zone Statistics

Statistic Description
fwd.queries Number of queries sent to the DNS cache that matched a configured forward zone.
fwd.responses Number of responses returned from a configured forward zone's nameserver, whether they were good responses or SERVFAIL.

Local Zones

Applicable only to the Transparent and Resolver caches, a local zone contains resource records that a DNS cache uses to resolve matching DNS queries with authoritative DNS responses. The zoneType attribute of the local zone determines how the cache handles a DNS query that does not match the local zone.

Parameter Description
deny For a non-matching query, the cache drops the DNS query. This is an example of a response to a non-matching query: DNS request timed out.
redirect For a non-matching query, when the query is for a subdomain of the local zone, the cache returns the same response that it would for the local zone. For example, if you add the local zone siterequest.com, the cache returns the same response to queries for wiki.siterequest.com. and download.wiki.siterequest.com. This is an example of a response to a non-matching query: NOERROR rcode returned and example.com. NOT resolved as expected.
refuse For a non-matching query, the cache returns a REFUSED message in the DNS response. This is an example of a response to a non-matching query: REFUSED rcode returned and example.com. NOT resolved as expected.
static For a non-matching query, the cache returns a NODATA or NXDOMAIN in the DNS response, which also includes the SOA record if the local zone contains one. This is an example of a response to a non-matching query: NOERROR rcode returned and example.com. NOT resolved as expected.
transparent Transparent is the default value. For a non-matching query, the cache performs a pass-through or iterative resolution of the DNS query. If the query matches, but no resource records are available, the cache returns a response with a NoData message. This is an example of a response to a non-matching query: NOERROR rcode returned and example.com. NOT resolved as expected.
type-transparent For a non-matching query, or a query for a matching domain name, but with a request for a record of a different type, the cache performs a pass-through or iterative resolution of the DNS query; however, if the query matches, but no resource records are available, the cache does not return a response with a NoData message. This is an example of a response to a non-matching query: DNS request resolved to example.com. as expected.

Local Zone Statistics

Statistic Description
local.queries Number of queries that match a subdomain of a local zone. These might not be an exact local zone rrset match.
local.responses Number of responses generated from an exact local zone's rrset match.

Sub-Caches

The DNS Cache is composed of a series of “sub-caches”, each of which serves a specific purpose for caching the various records that make up a DNS response.

Message

The message sub-cache is used to cache the complete DNS response sent to the originating client. The parts of this response include the question section, answer section, authority section and additional records, as well as all relevant header information sent back to the client.

An entry in the message sub-cache contains a query name, a query type, a query class, and query flags. This entry will then store information related to resource records in the rrset sub-cache used to generate the response sent back to the originating client.

Message Sub-Cache Statistics

Statistic Description
msg.hits Number of times the message sub-cache was checked for an entry, and a valid (and unexpired) entry was found.
msg.misses Number of times the message sub-cache was checked for an entry, and a valid (and unexpired) entry was not found.
msg.inserts Number of times that a new entry that did not currently exist (or existed but was expired) in the message sub-cache was inserted into the message sub-cache.
msg.updates Number of times that a valid (and unexpired) entry was updated in the message sub-cache.
msg.evictions Number of times that a valid (and unexpired) entry was removed from the message sub-cache to make space for a newer response.
msg.evictions_mempressure Number of times that a valid (and unexpired) entry was removed from the message sub-cache due to memory pressure constraints.
msg.ts_usecs_bytes_allocated Internally used to determine the last time the message sub-cache size allocation was changed.
msg.bytes_allocated Number of bytes currently allocated to the message sub-cache across the entire TMM process
msg.evictions_rate Average number of entries evicted from the message sub-cache per second.
msg.modifications_rate Average number of entries modified in the message sub-cache per second.

Resource Record Set

The resource record set (rrset) sub-cache contains records related to all rrsets that have been received by upstream DNS nameservers.

An entry in the resource record set sub-cache contains a domain name, an rrset type, and an rrset class. This entry will then store all relevant resource record set data related to the rrset type.

Resource Record Set Sub-Cache Statistics

Statistic Description
rrset.hits Number of times the resource record set sub-cache was checked for an entry, and a valid (and unexpired) entry was found.
rrset.misses Number of times the resource record set sub-cache was checked for an entry, and a valid (and unexpired) entry was not found.
rrset.inserts Number of times that a new entry that did not currently exist (or existed but was expired) in the resource record set sub-cache was inserted into the resource record set sub-cache.
rrset.updates Number of times that a valid (and unexpired) entry was updated in the resource record set sub-cache.
rrset.evictions Number of times that a valid (and unexpired) entry was removed from the resource record set sub-cache to make space for a newer response.
rrset.evictions_mempressure Number of times that a valid (and unexpired) entry was removed from the resource record set sub-cache due to memory pressure constraints.
rrset.ts_usecs_bytes_allocated Internally used to determine the last time the resource record set sub-cache size allocation was changed.
rrset.bytes_allocated Number of bytes currently allocated to the resource record set sub-cache across the entire TMM process
rrset.evictions_rate Average number of entries evicted from the resource record set sub-cache per second.
rrset.modifications_rate Average number of entries modified in the resource record set sub-cache per second.

Nameserver

In addition to the information available in the NS Resource Record set, the nameserver cache contains useful for keeping track of pending queries to upstream DNS nameservers. It specifically keeps track of things like TTL, RTT, whether nameserver uses EDNS, and the Lameness of the particular nameserver.

An entry in the nameserve sub-cache contains a domain name and IP address, and it will store information about that zones TTL, RTT, EDNS Status, Lameness, and Timeout information.

Nameserver Sub-Cache Statistics

Statistic Description
nameserver.hits Number of times the nameserver sub-cache was checked for an entry, and a valid (and unexpired) entry was found.
nameserver.misses Number of times the nameserver sub-cache was checked for an entry, and a valid (and unexpired) entry was not found.
nameserver.inserts Number of times that a new entry that did not currently exist (or existed but was expired) in the nameserver sub-cache was inserted into the nameserver sub-cache.
nameserver.updates Number of times that a valid (and unexpired) entry was updated in the nameserver sub-cache.
nameserver.evictions Number of times that a valid (and unexpired) entry was removed from the nameserver sub-cache to make space for a newer response.
nameserver.evictions_mempressure Number of times that a valid (and unexpired) entry was removed from the nameserver sub-cache due to memory pressure constraints.
nameserver.ts_usecs_bytes_allocated Internally used to determine the last time the nameserver sub-cache size allocation was changed.
nameserver.bytes_allocated Number of bytes currently allocated to the nameserver sub-cache across the entire TMM process
nameserver.evictions_rate Average number of entries evicted from the nameserver sub-cache per second.
nameserver.modifications_rate Average number of entries modified in the nameserver sub-cache per second.

Key

The key cache is used by the Validating Resolver (Not Yet Implemented) to store DNSKEYs.

An antry for the key sub-cache contains a domain name and a class, and it will store information about the key’s TTL, algorithm, algorithm, and rrset type secured.

Note: Validating Resolver is not currently implemented.

Key Sub-Cache Statistics

Statistic Description
key.hits Number of times the key sub-cache was checked for an entry, and a valid (and unexpired) entry was found.
key.misses Number of times the key sub-cache was checked for an entry, and a valid (and unexpired) entry was not found.
key.inserts Number of times that a new entry that did not currently exist (or existed but was expired) in the key sub-cache was inserted into the key sub-cache.
key.updates Number of times that a valid (and unexpired) entry was updated in the key sub-cache.
key.evictions Number of times that a valid (and unexpired) entry was removed from the key sub-cache to make space for a newer response.
key.evictions_mempressure Number of times that a valid (and unexpired) entry was removed from the key sub-cache due to memory pressure constraints.
key.ts_usecs_bytes_allocated Internally used to determine the last time the key sub-cache size allocation was changed.
key.bytes_allocated Number of bytes currently allocated to the key sub-cache across the entire TMM process
key.evictions_rate Average number of entries evicted from the key sub-cache per second.
key.modifications_rate Average number of entries modified in the key sub-cache per second.

A Mesh Of Query States

The DNS Cache uses a mesh of query states in order to track and store all resource record entries it has received from upstream DNS nameservers. This allows the cache to know what resource record sets it already has available and to make it easy to determine which record sets it is missing in order respond to an incoming client’s DNS query.

These query states contain information about pending queries (per query-name, query-type, and query class) and maintain relationships with other pending queries which are waiting for information from this query. For example, there may be a query state waiting on a response for www.example.com, which is itself waiting for a response from an upstream DNS nameserver for example.com. In this case, www.example.com is a super-state waiting for the sub-query state of example.com. It is is possible that a query for mail.example.com gets a response saved to the DNS cache before the query to example.com gets a response. At this point, the query state for mail.example.com would know that it also needs the response for example.com and would wait for that information to be returned before it finishes generating it’s response for mail.example.com. Once the response for example.com is received, then queries for both www.example.com and mail.example.com would be sent to the example.com nameserver.

Another benefit of these query states is they allow specific portions of a resolution to be cached, and that portion can then be retrieved locally without sending a query off-box to an upstream DNS server.

Continuing the above example, if after www.example.com and mail.example.com are fully resolved, and a query for about.example.com comes into the cache, the cache will already have information cached for example.com and can simply send it’s query for about.example.com to example.com’s nameserver. It will search the relevant sub-caches for the information it is looking for, and only send queries to upstream DNS nameservers when it cannot find relevant information in these sub-caches.

This only happens when the cache is unable to provide an answer to the client’s query from it’s configured local zones or forward zones.

Note on Maximum Concurrent Queries Connections

The DNS Resolver configuration object “max-concurrent-queries” represents the maximum number of simultaneously pending DNS queries sent to upstream DNS nameservers. The number of “max-concurrent-queries” is evenly divided between two lists that hold all pending queries, a “forever” list and a “jostle” list. The purpose of these two lists is to allow some queries to run to completion while having another list of queries that can be cancelled and replaced with new queries. Specifically, an entry in the “forever” list will run to completion, while an entry in the “jostle” list will potentially be cancelled and replaced. When one of these lists is full (half of the configured max-concurrent-queries setting) then entries will be moved to maximize the number of entries in the “forever” list.

Mesh Statistics

Statistic Description
mesh.total_callbacks Number of upstream responses or timeouts handled.
mesh.num_reply_states Number of current pending queries to upstream DNS nameservers in both the "jostle" list and "forever" list.
mesh.forever_states Number of current pending queries to upstream DNS nameservers in the "forever" list.
mesh.detached_states Number of pending states that have not received any replies from upstream DNS nameservers, and have no other mesh-states waiting for it's response.
mesh.replies_sent Unused, replaced by queries statistic.
mesh.stats_jostled Number of upstream queries dropped due to running out of space after query was sent and before a response was received.
mesh.stats_dropped Number of upstream queries dropped before being sent.
mesh.udp_queries Number of UDP queries sent to upstream DNS nameservers.
mesh.tcp_queries Number of TCP queries sent to upstream DNS nameservers.
mesh.responses Number of responses received for queries sent to upstream DNS nameservers.
mesh.queries_rate Average number of queries per second send from the cache to upstream DNS nameservers.
mesh.wait_response Number of pending queries sent to upstream DNS nameservers that have not yet received a response.
mesh.udp_wait_send Number of UDP queries currently waiting to be sent to upstream DNS nameservers.
mesh.tcp_wait_send Number of TCP queries currently waiting to be sent to upstream DNS nameservers.
mesh.unwanted_replies Number of unwanted or unsolicited replies received from upstream DNS nameservers, or expected replies received over the wrong port.
mesh.hits Incoming query was able to be resolved based upon already cached data, no further resolution required.
mesh.misses Incoming query was not able to be resolved solely with previously cached data, further resolution required.
mesh.client_wait_response Number of client queries waiting for a response from the cache.
mesh.dns64reqs Number of DNS64 requests sent to upstream DNS nameservers.
mesh.dns64xlated Number of responses where DNS64 AAAA prefix was used to synthesize an AAAA record from an A record.
mesh.dns64nodata Number of NODATA responses to DNS64 queries send to upstream DNS nameservers.

Queries to Upstream DNS Nameservers

When the DNS cache is sending queries to upstream DNS nameservers, the queries are not sent by the Virtual Server configured to use the DNS cache. Instead, it communicates directly to the upstream DNS nameservers in order to send queries and receive responses. For TCP connections, the cache takes full ownership of these connections for their entire lifetime, establishing, tearing down, and timing out these connections. For UDP, the cache simply generates the packet and sends them out while awaiting for responses to sent queries.

Upstream DNS Nameserver Error Statistics

Statistic Description
ns_resp_err.memory Number of times a connection to an upstream DNS nameserver was unsuccessful due to an out of memory condition.
ns_resp_err.port_v4 Number of times a connection to an upstream DNS nameserver was unsuccessful due to not having any v4 ports available to use.
ns_resp_err.port_v6 Number of times a connection to an upstream DNS nameserver was unsuccessful due to not having any v6 ports available to use.
ns_resp_err.route_v4 Number of times a connection to an upstream DNS nameserver was unsuccessful due to not having a route to the specified v4 host.
ns_resp_err.route_v6 Number of times a connection to an upstream DNS nameserver was unsuccessful due to not having a route to the specified v4 host.
ns_resp_err.timeout Number of times a connection to an upstream DNS nameserver was unsuccessful due to a connection timeout.
ns_resp_err.servfail Number of responses from an upstream DNS nameserver returned with an rcode of SERVFAIL.
ns_resp_err.formerr Number of responses from an upstream DNS nameserver returned with an rcode of FORMERR.
ns_resp_err.other Number of times a connection to an upstream DNS nameserver was unsuccessful or was returned a response with an rcode that isn't covered by the previously defined conditions.

Upstream DNS Namserver UDP Connection Statistics

Statistic Description
udp.pkts_in Total number of UDP packets received from upstream DNS nameservers.
udp.pkts_out Total number of UDP packets sent to upstream DNS nameservers.
udp.bytes_in Total number of bytes received over UDP from upstream DNS nameservers.
udp.bytes_out Total number of bytes sent over UDP to upstream DNS nameservers.
udp.max_conns Maximum number of simultaneous pending UDP connections to upstream DNS nameservers.
udp.tot_conns Total number of UDP connections established to upstream DNS nameservers.
udp.cur_conns Current number of outstanding UDP connections established to upstream DNS nameservers.

Upstream DNS Nameserver TCP Connection Statistics

Statistic Description
tcp.pkts_in Total number of TCP packets received from upstream DNS nameservers.
tcp.pkts_out Total number of TCP packets sent to upstream DNS nameservers.
tcp.bytes_in Total number of bytes received over TCP from upstream DNS nameservers.
tcp.bytes_out Total number of bytes sent over TCP to upstream DNS nameservers.
tcp.max_conns Maximum number of simultaneous pending TCP connections to upstream DNS nameservers.
tcp.tot_conns Total number of TCP connections established to upstream DNS nameservers.
tcp.cur_conns Current number of outstanding TCP connections established to upstream DNS nameservers.

Other Statistics

The following statistics are also available:

Statistic Description
name Name of the DNS Cache.
cache_index Internally used cache index number.
queries Number of queries that have been sent to the cache.
responses Number of responses that the cache was able to generate for queries it received.
responses_rate Number of responses the cache generated within the previous 1 second of time.
response_time_sync Running average time for synchronous cache responses.
response_time_async Running average time for asynchronous cache responses.
cb_ctx_cnt Number of currently pending queries sent to the DNS cache.
sync Number of responses the cache was able to generate without needing to establish any connections to an upstream DNS nameserver.
async Number of responses the cache generated using data that had to be obtained from upstream DNS nameservers.
failure_resolv Number of malformed or corrupted responses received from from upstream DNS nameservers.
failure_server Internal cache was unable to accept the query due to resource limitations such as an out of memory condition, or too many pending queries to upstream DNS nameservers.
failure_cf Response generated by cache that cannot be sent to waiting client due to client connection being closed.
failure_send Response generated by cache that cannot be sent to waiting client due to a resource constraint (such as out-of-memory), or client is in the process of closing their connection.
sec_unchecked Number of rrsets or messages that have yet to be validated.
sec_bogus Number of rrsets or messages that failed to validate (according to local policy) but should have been validated.
sec_indeterminate Number of rrsets or messages that were found to be insecure, but not authoritatively so. Generally, this means that the rrset is not below a configured trust anchor.
sec_insecure Number of rrsets or messages that were found to be authoritatively insecure. Generally, this means that the rrset is below a trust anchor, but also below a verified and insecure delegation.
sec_secure Number of rrsets or messages that have been validated as secure against a local policy.
rpz_rewrites Number of queries that were generated from a configured response-policy-zone.