DNS parameters for Consul agent configuration files

The page provides reference information for DNS parameters in a Consul agent configuration file.

DNS and Domain Parameters

• alt_domain - This parameter allows Consul to respond to DNS queries in an alternate domain, in addition to the primary domain. If unset, no alternate domain is used. Equivalent to the -alt-domain command-line flag.

• dns_config This object allows a number of sub-keys to be set which can tune how DNS queries are serviced. Refer to DNS caching for more information.

  The following sub-keys are available:

  • allow_stale - Enables a stale query for DNS information. This allows any Consul server, rather than only the leader, to service the request. The advantage of this is you get linear read scalability with Consul servers. In versions of Consul prior to 0.7, this defaulted to false, meaning all requests are serviced by the leader, providing stronger consistency but less throughput and higher latency. In Consul 0.7 and later, this defaults to true for better utilization of available servers.

  • max_stale - When allow_stale is specified, this is used to limit how stale results are allowed to be. If a Consul server is behind the leader by more than max_stale, the query will be re-evaluated on the leader to get more up-to-date results. Prior to Consul 0.7.1 this defaulted to 5 seconds; in Consul 0.7.1 and later this defaults to 10 years ("87600h") which effectively allows DNS queries to be answered by any server, no matter how stale. In practice, servers are usually only milliseconds behind the leader, so this lets Consul continue serving requests in long outage scenarios where no leader can be elected.

  • node_ttl - By default, this is "0s", so all node lookups are served with a 0 TTL value. DNS caching for node lookups can be enabled by setting this value. This should be specified with the "s" suffix for second or "m" for minute.

  • service_ttl - This is a sub-object which allows for setting a TTL on service lookups with a per-service policy. The "*" wildcard service can be used when there is no specific policy available for a service. By default, all services are served with a 0 TTL value. DNS caching for service lookups can be enabled by setting this value.

  • enable_truncate - If set to true, a UDP DNS query that would return more than 3 records, or more than would fit into a valid UDP response, will set the truncated flag, indicating to clients that they should re-query using TCP to get the full set of records.

  • only_passing - If set to true, any nodes whose health checks are warning or critical will be excluded from DNS results. If false, the default, only nodes whose health checks are failing as critical will be excluded. For service lookups, the health checks of the node itself, as well as the service-specific checks are considered. For example, if a node has a health check that is critical then all services on that node will be excluded because they are also considered critical.

  • recursor_strategy - If set to sequential, Consul will query recursors in the order listed in the recursors option. If set to random, Consul will query an upstream DNS resolvers in a random order. Defaults to sequential.

  • recursor_timeout - Timeout used by Consul when recursively querying an upstream DNS server. See recursors for more details. Default is 2s. This is available in Consul 0.7 and later.

  • disable_compression - If set to true, DNS responses will not be compressed. Compression was added and enabled by default in Consul 0.7.

  • udp_answer_limit - Limit the number of resource records contained in the answer section of a UDP-based DNS response. This parameter applies only to UDP DNS queries that are less than 512 bytes. This setting is deprecated and replaced in Consul 1.0.7 by a_record_limit.

  • a_record_limit - Limit the number of resource records contained in the answer section of a A, AAAA or ANY DNS response (both TCP and UDP). When answering a question, Consul will use the complete list of matching hosts, shuffle the list randomly, and then limit the number of answers to a_record_limit (default: no limit). This limit does not apply to SRV records.

    In environments where RFC 3484 Section 6 Rule 9 is implemented and enforced (i.e. DNS answers are always sorted and therefore never random), clients may need to set this value to 1 to preserve the expected randomized distribution behavior (note: RFC 3484 has been obsoleted by RFC 6724 and as a result it should be increasingly uncommon to need to change this value with modern resolvers).

  • enable_additional_node_meta_txt - When set to true, Consul will add TXT records for Node metadata into the Additional section of the DNS responses for several query types such as SRV queries. When set to false those records are not emitted. This does not impact the behavior of those same TXT records when they would be added to the Answer section of the response like when querying with type TXT or ANY. This defaults to true.

  • soa Allow to tune the setting set up in SOA. Non specified values fallback to their default values, all values are integers and expressed as seconds.

    The following settings are available:

    • expire - Configure SOA Expire duration in seconds, default value is 86400, ie: 24 hours.

    • min_ttl - Configure SOA DNS minimum TTL. As explained in RFC-2308 this also controls negative cache TTL in most implementations. Default value is 0, ie: no minimum delay or negative TTL.

    • refresh - Configure SOA Refresh duration in seconds, default value is 3600, ie: 1 hour.

    • retry - Configures the Retry duration expressed in seconds, default value is 600, ie: 10 minutes.

  • use_cache - When set to true, DNS resolution will use the agent cache described in agent caching. This setting affects all service and prepared queries DNS requests. Implies allow_stale

  • cache_max_age - When use_cache is enabled, the agent will attempt to re-fetch the result from the servers if the cached value is older than this duration. See: agent caching.

    Note that unlike the max-age HTTP header, a value of 0 for this field is equivalent to "no max age". To get a fresh value from the cache use a very small value of 1ns instead of 0.

  • prefer_namespace EnterpriseEnterprise Deprecated in Consul 1.11. Use the canonical DNS format for enterprise service lookups instead. - When set to true, in a DNS query for a service, a single label between the domain and the service label is treated as a namespace name instead of a datacenter. When set to false, the default, the behavior is the same as non-Enterprise versions and treats the single label as the datacenter.

• domain - By default, Consul responds to DNS queries in the consul. domain. This flag can be used to change that domain. All queries in this domain are assumed to be handled by Consul and will not be recursively resolved.

• recursors - Provides addresses of upstream DNS servers that are used to recursively resolve queries if they are not inside the service domain for Consul. For example, a node can use Consul directly as a DNS server, and if the record is outside of the "consul." domain, the query will be resolved upstream. As of Consul 1.0.1 recursors can be provided as IP addresses or as go-sockaddr templates. IP addresses are resolved in order, and duplicates are ignored.