2014-02-19 19:05:42 +00:00
---
layout: "docs"
page_title: "DNS Interface"
sidebar_current: "docs-agent-dns"
2014-10-19 23:40:10 +00:00
description: |-
2015-01-31 04:32:57 +00:00
One of the primary query interfaces for Consul is DNS. The DNS interface allows applications to make use of service discovery without any high-touch integration with Consul.
2014-02-19 19:05:42 +00:00
---
# DNS Interface
2014-11-26 13:32:19 +00:00
One of the primary query interfaces for Consul is DNS.
2014-02-19 19:05:42 +00:00
The DNS interface allows applications to make use of service
2015-01-31 18:01:00 +00:00
discovery without any high-touch integration with Consul.
2014-02-19 19:05:42 +00:00
2015-01-31 18:01:00 +00:00
For example, instead of making HTTP API requests to Consul,
a host can use the DNS server directly via name lookups
2016-11-25 16:00:02 +00:00
like `redis.service.us-east-1.consul` . This query automatically
translates to a lookup of nodes that provide the `redis` service,
are located in the `us-east-1` datacenter, and have no failing health checks.
2015-01-31 18:01:00 +00:00
It's that simple!
2014-02-19 19:05:42 +00:00
2015-01-31 18:07:21 +00:00
There are a number of configuration options that are important for the DNS interface,
2015-03-23 19:48:35 +00:00
specifically [`client_addr` ](/docs/agent/options.html#client_addr ),
[`ports.dns` ](/docs/agent/options.html#dns_port ), [`recursors` ](/docs/agent/options.html#recursors ),
[`domain` ](/docs/agent/options.html#domain ), and [`dns_config` ](/docs/agent/options.html#dns_config ).
2016-11-25 16:00:02 +00:00
By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.`
2015-03-23 19:48:35 +00:00
domain, without support for further DNS recursion. Please consult the
[documentation on configuration options ](/docs/agent/options.html ),
specifically the configuration items linked above, for more details.
2014-02-19 19:05:42 +00:00
There are a few ways to use the DNS interface. One option is to use a custom
DNS resolver library and point it at Consul. Another option is to set Consul
2015-03-23 19:48:35 +00:00
as the DNS server for a node and provide a
[`recursors` ](/docs/agent/options.html#recursors ) configuration so that non-Consul queries
2014-02-19 19:05:42 +00:00
can also be resolved. The last method is to forward all queries for the "consul."
2015-01-31 17:51:28 +00:00
domain to a Consul agent from the existing DNS server.
You can experiment with Consul's DNS server on the command line using tools such as `dig` :
2014-02-19 19:05:42 +00:00
$ dig @127 .0.0.1 -p 8600 redis.service.dc1.consul. ANY
2016-11-25 16:00:02 +00:00
-> **Note:** In DNS, all queries are case-insensitive. A lookup of `PostgreSQL.node.dc1.consul` will find all nodes named `postgresql` .
2015-01-31 18:07:21 +00:00
2014-02-19 19:05:42 +00:00
## Node Lookups
2015-01-31 17:51:28 +00:00
To resolve names, Consul relies on a very specific format for queries.
There are fundamentally two types of queries: node lookups and service lookups.
A node lookup, a simple query for the address of a named node, looks like this:
2014-02-19 19:05:42 +00:00
2015-09-24 06:09:38 +00:00
< node > .node[.datacenter].< domain >
2014-02-19 19:05:42 +00:00
2016-11-25 16:00:02 +00:00
For example, if we have a `foo` node with default settings, we could
look for `foo.node.dc1.consul.` The datacenter is an optional part of
the FQDN: if not provided, it defaults to the datacenter of the agent.
If we know `foo` is running in the same datacenter as our local agent,
we can instead use `foo.node.consul.` This convention allows for terse
syntax where appropriate while supporting queries of nodes in remote
datacenters as necessary.
2014-02-19 19:05:42 +00:00
2016-11-25 16:00:02 +00:00
For a node lookup, the only records returned are A records containing
the IP address of the node.
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
```text
2015-01-31 17:51:28 +00:00
$ dig @127 .0.0.1 -p 8600 foo.node.consul ANY
2014-02-19 19:05:42 +00:00
2015-01-31 17:51:28 +00:00
; << >> DiG 9.8.3-P1 << >> @127 .0.0.1 -p 8600 foo.node.consul ANY
2014-10-19 23:40:10 +00:00
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER< < - opcode: QUERY , status: NOERROR , id: 24355
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 0
;; WARNING: recursion requested but not available
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
;; QUESTION SECTION:
2015-01-31 17:51:28 +00:00
;foo.node.consul. IN ANY
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
;; ANSWER SECTION:
2015-01-31 17:51:28 +00:00
foo.node.consul. 0 IN A 10.1.10.12
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
;; AUTHORITY SECTION:
consul. 0 IN SOA ns.consul. postmaster.consul. 1392836399 3600 600 86400 0
```
2014-02-19 19:05:42 +00:00
## Service Lookups
2016-11-25 18:25:09 +00:00
A service lookup is used to query for service providers. Service queries support
2015-01-31 17:51:28 +00:00
two lookup methods: standard and strict [RFC 2782 ](https://tools.ietf.org/html/rfc2782 ).
2014-02-19 19:05:42 +00:00
2014-11-26 13:32:19 +00:00
### Standard Lookup
2014-08-18 19:45:56 +00:00
2014-11-26 13:32:19 +00:00
The format of a standard service lookup is:
2014-08-18 19:45:56 +00:00
2015-09-24 06:16:34 +00:00
[tag.]< service > .service[.datacenter].< domain >
2014-02-19 19:05:42 +00:00
2016-11-25 16:00:02 +00:00
The `tag` is optional, and, as with node lookups, the `datacenter` is as
well. If no tag is provided, no filtering is done on tag. If no
datacenter is provided, the datacenter of this Consul agent is assumed.
2015-01-31 17:51:28 +00:00
2016-11-25 16:00:02 +00:00
If we want to find any redis service providers in our local datacenter,
2016-11-29 23:01:38 +00:00
we could query `redis.service.consul.` If we want to find the PostgreSQL
2016-11-25 16:00:02 +00:00
primary in a particular datacenter, we could query
`primary.postgresql.service.dc2.consul.`
2014-02-19 19:05:42 +00:00
The DNS query system makes use of health check information to prevent routing
to unhealthy nodes. When a service query is made, any services failing their health
2015-01-31 17:51:28 +00:00
check or failing a node system check will be omitted from the results. To allow
2014-02-19 19:05:42 +00:00
for simple load balancing, the set of nodes returned is also randomized each time.
2015-01-31 18:17:43 +00:00
These mechanisms make it easy to use DNS along with application-level retries
2015-01-31 17:51:28 +00:00
as the foundation for an auto-healing service oriented architecture.
2014-02-19 19:05:42 +00:00
2015-01-31 17:51:28 +00:00
For standard services queries, both A and SRV records are supported. SRV records
provide the port that a service is registered on, enabling clients to avoid relying
2014-04-08 19:18:05 +00:00
on well-known ports. SRV records are only served if the client specifically requests
2015-01-31 17:51:28 +00:00
them, like so:
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
```text
$ dig @127 .0.0.1 -p 8600 consul.service.consul SRV
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
; << >> DiG 9.8.3-P1 << >> @127 .0.0.1 -p 8600 consul.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER< < - opcode: QUERY , status: NOERROR , id: 50483
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
;; QUESTION SECTION:
;consul.service.consul. IN SRV
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
;; ANSWER SECTION:
consul.service.consul. 0 IN SRV 1 1 8300 foobar.node.dc1.consul.
2014-02-19 19:05:42 +00:00
2014-10-19 23:40:10 +00:00
;; ADDITIONAL SECTION:
foobar.node.dc1.consul. 0 IN A 10.1.10.12
```
2014-02-19 19:05:42 +00:00
2014-11-26 13:32:19 +00:00
### RFC 2782 Lookup
2014-08-18 19:45:56 +00:00
2014-11-26 13:32:19 +00:00
The format for RFC 2782 SRV lookups is:
2014-08-18 19:45:56 +00:00
2017-01-30 18:36:48 +00:00
_<service>._ < protocol > [.service][.datacenter][.domain]
2014-08-18 19:45:56 +00:00
2014-11-26 13:32:19 +00:00
Per [RFC 2782 ](https://tools.ietf.org/html/rfc2782 ), SRV queries should use
2016-11-25 16:00:02 +00:00
underscores, `_` , as a prefix to the `service` and `protocol` values in a query to
2014-08-18 19:45:56 +00:00
prevent DNS collisions. The `protocol` value can be any of the tags for a
2016-11-25 16:00:02 +00:00
service. If the service has no tags, `tcp` should be used. If `tcp`
2014-08-18 19:45:56 +00:00
is specified as the protocol, the query will not perform any tag filtering.
2016-11-25 16:00:02 +00:00
Other than the query format and default `tcp` protocol/tag value, the behavior
2014-08-18 19:45:56 +00:00
of the RFC style lookup is the same as the standard style of lookup.
2016-11-25 16:00:02 +00:00
If you registered the service `rabbitmq` on port 5672 and tagged it with `amqp` ,
you could make an RFC 2782 query for its SRV record as `_rabbitmq._amqp.service.consul` :
2014-08-18 19:45:56 +00:00
2014-10-19 23:40:10 +00:00
```text
$ dig @127 .0.0.1 -p 8600 _rabbitmq._amqp.service.consul SRV
2014-08-18 19:45:56 +00:00
2014-10-19 23:40:10 +00:00
; << >> DiG 9.8.3-P1 << >> @127 .0.0.1 -p 8600 _rabbitmq._amqp.service.consul ANY
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER< < - opcode: QUERY , status: NOERROR , id: 52838
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
2014-08-18 19:45:56 +00:00
2014-10-19 23:40:10 +00:00
;; QUESTION SECTION:
;_rabbitmq._amqp.service.consul. IN SRV
2014-08-18 19:45:56 +00:00
2014-10-19 23:40:10 +00:00
;; ANSWER SECTION:
_rabbitmq._amqp.service.consul. 0 IN SRV 1 1 5672 rabbitmq.node1.dc1.consul.
2014-08-18 19:45:56 +00:00
2014-10-19 23:40:10 +00:00
;; ADDITIONAL SECTION:
rabbitmq.node1.dc1.consul. 0 IN A 10.1.11.20
```
2014-08-18 19:45:56 +00:00
2015-01-31 17:59:03 +00:00
Again, note that the SRV record returns the port of the service as well as its IP.
2015-11-14 20:45:34 +00:00
### Prepared Query Lookups
The format of a prepared query lookup is:
< query or name > .query[.datacenter].< domain >
The `datacenter` is optional, and if not provided, the datacenter of this Consul
agent is assumed.
The `query or name` is the ID or given name of an existing
2017-04-04 16:33:22 +00:00
[Prepared Query ](/api/query.html ). These behave like standard service
2015-11-14 20:45:34 +00:00
queries but provide a much richer set of features, such as filtering by multiple
tags and automatically failing over to look for services in remote datacenters if
2016-03-03 05:56:03 +00:00
no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also
2017-04-04 16:33:22 +00:00
added support for [prepared query templates ](/api/query.html#templates )
2016-03-03 05:56:03 +00:00
which can match names using a prefix match, allowing one template to apply to
potentially many services.
2015-11-14 20:45:34 +00:00
To allow for simple load balancing, the set of nodes returned is randomized each time.
Both A and SRV records are supported. SRV records provide the port that a service is
registered on, enabling clients to avoid relying on well-known ports. SRV records are
only served if the client specifically requests them.
2014-08-18 19:45:56 +00:00
### UDP Based DNS Queries
2014-05-20 23:43:44 +00:00
When the DNS query is performed using UDP, Consul will truncate the results
without setting the truncate bit. This is to prevent a redundant lookup over
2014-11-26 13:32:19 +00:00
TCP that generates additional load. If the lookup is done over TCP, the results
2014-05-20 23:43:44 +00:00
are not truncated.
2014-02-19 19:05:42 +00:00
2014-06-09 00:26:41 +00:00
## Caching
By default, all DNS results served by Consul set a 0 TTL value. This disables
caching of DNS results. However, there are many situations in which caching is
desirable for performance and scalability. This is discussed more in the guide
for [DNS Caching ](/docs/guides/dns-cache.html ).
2016-02-07 18:56:47 +00:00
## WAN Address Translation
2016-05-29 17:24:44 +00:00
By default, Consul DNS queries will return a node's local address, even when
2016-02-07 18:56:47 +00:00
being queried from a remote datacenter. If you need to use a different address
to reach a node from outside its datacenter, you can configure this behavior
using the [`advertise-wan` ](/docs/agent/options.html#_advertise-wan ) and
[`translate_wan_addrs` ](/docs/agent/options.html#translate_wan_addrs ) configuration
options.