1--- 2layout: docs 3page_title: DNS Interface 4sidebar_title: DNS Interface 5description: >- 6 One of the primary query interfaces for Consul is DNS. The DNS interface 7 allows applications to make use of service discovery without any high-touch 8 integration with Consul. 9--- 10 11# DNS Interface 12 13One of the primary query interfaces for Consul is DNS. 14The DNS interface allows applications to make use of service 15discovery without any high-touch integration with Consul. 16 17For example, instead of making HTTP API requests to Consul, 18a host can use the DNS server directly via name lookups 19like `redis.service.us-east-1.consul`. This query automatically 20translates to a lookup of nodes that provide the `redis` service, 21are located in the `us-east-1` datacenter, and have no failing health checks. 22It's that simple! 23 24There are a number of configuration options that are important for the DNS interface, 25specifically [`client_addr`](/docs/agent/options#client_addr), 26[`ports.dns`](/docs/agent/options#dns_port), [`recursors`](/docs/agent/options#recursors), 27[`domain`](/docs/agent/options#domain), and [`dns_config`](/docs/agent/options#dns_config). 28By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.` 29domain, without support for further DNS recursion. Please consult the 30[documentation on configuration options](/docs/agent/options), 31specifically the configuration items linked above, for more details. 32 33There are a few ways to use the DNS interface. One option is to use a custom 34DNS resolver library and point it at Consul. Another option is to set Consul 35as the DNS server for a node and provide a 36[`recursors`](/docs/agent/options#recursors) configuration so that non-Consul queries 37can also be resolved. The last method is to forward all queries for the "consul." 38domain to a Consul agent from the existing DNS server. Review the 39[DNS Forwarding guide](https://learn.hashicorp.com/consul/security-networking/forwarding?utm_source=consul.io&utm_medium=docs) for examples. 40 41You can experiment with Consul's DNS server on the command line using tools such as `dig`: 42 43```shell 44$ dig @127.0.0.1 -p 8600 redis.service.dc1.consul. ANY 45``` 46 47-> **Note:** In DNS, all queries are case-insensitive. A lookup of `PostgreSQL.node.dc1.consul` will find all nodes named `postgresql`. 48 49## Node Lookups 50 51To resolve names, Consul relies on a very specific format for queries. 52There are fundamentally two types of queries: node lookups and service lookups. 53A node lookup, a simple query for the address of a named node, looks like this: 54 55```text 56<node>.node[.datacenter].<domain> 57``` 58 59For example, if we have a `foo` node with default settings, we could 60look for `foo.node.dc1.consul.` The datacenter is an optional part of 61the FQDN: if not provided, it defaults to the datacenter of the agent. 62If we know `foo` is running in the same datacenter as our local agent, 63we can instead use `foo.node.consul.` This convention allows for terse 64syntax where appropriate while supporting queries of nodes in remote 65datacenters as necessary. 66 67For a node lookup, the only records returned are A and AAAA records 68containing the IP address, and TXT records containing the 69`node_meta` values of the node. 70 71```text 72$ dig @127.0.0.1 -p 8600 foo.node.consul ANY 73 74; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 foo.node.consul ANY 75; (1 server found) 76;; global options: +cmd 77;; Got answer: 78;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 24355 79;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 0 80;; WARNING: recursion requested but not available 81 82;; QUESTION SECTION: 83;foo.node.consul. IN ANY 84 85;; ANSWER SECTION: 86foo.node.consul. 0 IN A 10.1.10.12 87foo.node.consul. 0 IN TXT "meta_key=meta_value" 88foo.node.consul. 0 IN TXT "value only" 89 90 91;; AUTHORITY SECTION: 92consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0 93``` 94 95By default the TXT records value will match the node's metadata key-value 96pairs according to [RFC1464](https://www.ietf.org/rfc/rfc1464.txt). 97Alternatively, the TXT record will only include the node's metadata value when the 98node's metadata key starts with `rfc1035-`. 99 100## Service Lookups 101 102A service lookup is used to query for service providers. Service queries support 103two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782). 104 105By default, SRV weights are all set at 1, but changing weights is supported using the 106`Weights` attribute of the [service definition](/docs/agent/services). 107 108Note that DNS is limited in size per request, even when performing DNS TCP 109queries. 110 111For services having many instances (more than 500), it might not be possible to 112retrieve the complete list of instances for the service. 113 114When DNS SRV response are sent, order is randomized, but weights are not 115taken into account. In the case of truncation different clients using weighted SRV 116responses will have partial and inconsistent views of instances weights so the 117request distribution could be skewed from the intended weights. In that case, 118it is recommended to use the HTTP API to retrieve the list of nodes. 119 120### Standard Lookup 121 122The format of a standard service lookup is: 123 124```text 125[tag.]<service>.service[.datacenter].<domain> 126``` 127 128The `tag` is optional, and, as with node lookups, the `datacenter` is as 129well. If no tag is provided, no filtering is done on tag. If no 130datacenter is provided, the datacenter of this Consul agent is assumed. 131 132If we want to find any redis service providers in our local datacenter, 133we could query `redis.service.consul.` If we want to find the PostgreSQL 134primary in a particular datacenter, we could query 135`primary.postgresql.service.dc2.consul.` 136 137The DNS query system makes use of health check information to prevent routing 138to unhealthy nodes. When a service query is made, any services failing their health 139check or failing a node system check will be omitted from the results. To allow 140for simple load balancing, the set of nodes returned is also randomized each time. 141These mechanisms make it easy to use DNS along with application-level retries 142as the foundation for an auto-healing service oriented architecture. 143 144For standard services queries, both A and SRV records are supported. SRV records 145provide the port that a service is registered on, enabling clients to avoid relying 146on well-known ports. SRV records are only served if the client specifically requests 147them, like so: 148 149```text 150$ dig @127.0.0.1 -p 8600 consul.service.consul SRV 151 152; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 consul.service.consul ANY 153; (1 server found) 154;; global options: +cmd 155;; Got answer: 156;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50483 157;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 1, ADDITIONAL: 1 158;; WARNING: recursion requested but not available 159 160;; QUESTION SECTION: 161;consul.service.consul. IN SRV 162 163;; ANSWER SECTION: 164consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul. 165 166;; ADDITIONAL SECTION: 167foobar.node.dc1.consul. 0 IN A 10.1.10.12 168``` 169 170### RFC 2782 Lookup 171 172The format for RFC 2782 SRV lookups is: 173 174 _<service>._<protocol>[.service][.datacenter][.domain] 175 176Per [RFC 2782](https://tools.ietf.org/html/rfc2782), SRV queries should use 177underscores, `_`, as a prefix to the `service` and `protocol` values in a query to 178prevent DNS collisions. The `protocol` value can be any of the tags for a 179service. If the service has no tags, `tcp` should be used. If `tcp` 180is specified as the protocol, the query will not perform any tag filtering. 181 182Other than the query format and default `tcp` protocol/tag value, the behavior 183of the RFC style lookup is the same as the standard style of lookup. 184 185If you registered the service `rabbitmq` on port 5672 and tagged it with `amqp`, 186you could make an RFC 2782 query for its SRV record as `_rabbitmq._amqp.service.consul`: 187 188```text 189$ dig @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV 190 191; <<>> DiG 9.8.3-P1 <<>> @127.0.0.1 -p 8600 _rabbitmq._amqp.service.consul ANY 192; (1 server found) 193;; global options: +cmd 194;; Got answer: 195;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 52838 196;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1 197;; WARNING: recursion requested but not available 198 199;; QUESTION SECTION: 200;_rabbitmq._amqp.service.consul. IN SRV 201 202;; ANSWER SECTION: 203_rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul. 204 205;; ADDITIONAL SECTION: 206rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20 207``` 208 209Again, note that the SRV record returns the port of the service as well as its IP. 210 211### Prepared Query Lookups 212 213The format of a prepared query lookup is: 214 215```text 216<query or name>.query[.datacenter].<domain> 217``` 218 219The `datacenter` is optional, and if not provided, the datacenter of this Consul 220agent is assumed. 221 222The `query or name` is the ID or given name of an existing 223[Prepared Query](/api/query). These behave like standard service 224queries but provide a much richer set of features, such as filtering by multiple 225tags and automatically failing over to look for services in remote datacenters if 226no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also 227added support for [prepared query templates](/api/query#prepared-query-templates) 228which can match names using a prefix match, allowing one template to apply to 229potentially many services. 230 231To allow for simple load balancing, the set of nodes returned is randomized each time. 232Both A and SRV records are supported. SRV records provide the port that a service is 233registered on, enabling clients to avoid relying on well-known ports. SRV records are 234only served if the client specifically requests them. 235 236### Connect-Capable Service Lookups 237 238To find Connect-capable services: 239 240```text 241<service>.connect.<domain> 242``` 243 244This will find all [Connect-capable](/docs/connect) 245endpoints for the given `service`. A Connect-capable endpoint may be 246both a proxy for a service or a natively integrated Connect application. 247The DNS interface does not differentiate the two. 248 249Most services will use a [proxy](/docs/connect/proxies) that handles 250service discovery automatically and therefore won't use this DNS format. 251This DNS format is primarily useful for [Connect-native](/docs/connect/native) 252applications. 253 254This endpoint currently only finds services within the same datacenter 255and doesn't support tags. This DNS interface will be expanded over time. 256If you need more complex behavior, please use the 257[catalog API](/api/catalog). 258 259### Ingress Service Lookups 260 261To find ingress-enabled services: 262 263```text 264<service>.ingress.<domain> 265``` 266 267This will find all [ingress gateway](/docs/connect/ingress_gateway) 268endpoints for the given `service`. 269 270This endpoint currently only finds services within the same datacenter 271and doesn't support tags. This DNS interface will be expanded over time. 272If you need more complex behavior, please use the 273[catalog API](/api/catalog). 274 275### UDP Based DNS Queries 276 277When the DNS query is performed using UDP, Consul will truncate the results 278without setting the truncate bit. This is to prevent a redundant lookup over 279TCP that generates additional load. If the lookup is done over TCP, the results 280are not truncated. 281 282## Caching 283 284By default, all DNS results served by Consul set a 0 TTL value. This disables 285caching of DNS results. However, there are many situations in which caching is 286desirable for performance and scalability. This is discussed more in the guide 287for [DNS caching](https://learn.hashicorp.com/consul/security-networking/dns-caching). 288 289## WAN Address Translation 290 291By default, Consul DNS queries will return a node's local address, even when 292being queried from a remote datacenter. If you need to use a different address 293to reach a node from outside its datacenter, you can configure this behavior 294using the [`advertise-wan`](/docs/agent/options#_advertise-wan) and 295[`translate_wan_addrs`](/docs/agent/options#translate_wan_addrs) configuration 296options. 297 298## Namespaced Services <EnterpriseAlert inline /> 299 300Consul Enterprise 1.7.0 added support for namespaces including resolving namespaced 301services via DNS. To maintain backwards compatibility existing queries can be used 302and these will resolve services within the `default` namespace. However, for resolving 303services from other namespaces the following form can be used: 304 305```text 306[tag.]<service>.service.<namespace>.<datacenter>.<domain> 307``` 308 309This is the canonical name of a Consul Enterprise service with all parts present. Like 310Consul OSS some parts may be omitted but which parts depend on the value of the 311[`prefer_namespace` configuration](/docs/agent/options#dns_prefer_namespace). 312 313With `prefer_namespace` set to `true` the datacenter may be omitted and will be defaulted 314to the local agents datacenter: 315 316```text 317[tag.]<service>.service.<namespace>.<domain> 318``` 319 320With `prefer_namespace` set to `false` the namespace may be omitted and will be defaulted 321to the `default` namespace: 322 323```text 324[tag.]<service>.service.<datacenter> 325``` 326 327Finally, both the namespace and datacenter may be omitted and the service will be resolved 328in the `default` namespace and in the datacenter of the local agent. 329