diff --git a/website/source/docs/agent/dns.html.markdown b/website/source/docs/agent/dns.html.markdown
index fe0b1fa6e..46303a60d 100644
--- a/website/source/docs/agent/dns.html.markdown
+++ b/website/source/docs/agent/dns.html.markdown
@@ -19,7 +19,7 @@ with no failing health checks. It's that simple!
There are a number of [configuration options](/docs/agent/options.html) that
are important for the DNS interface. They are `client_addr`, `ports.dns`, `recursor`,
-and `domain`. By default Consul will listen on 127.0.0.1:8600 for DNS queries
+`domain`, and `dns_config`. By default Consul will listen on 127.0.0.1:8600 for DNS queries
in the "consul." domain, without support for DNS recursion.
There are a few ways to use the DNS interface. One option is to use a custom
@@ -118,3 +118,10 @@ without setting the truncate bit. This is to prevent a redundant lookup over
TCP which generate additional load. If the lookup is done over TCP, the results
are not truncated.
+## 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).
+
diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown
index b185a1f45..bc95aea78 100644
--- a/website/source/docs/agent/options.html.markdown
+++ b/website/source/docs/agent/options.html.markdown
@@ -183,6 +183,30 @@ definitions support being updated during a reload.
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.
+* `dns_config` - This object allows a number of sub-keys to be set which can tune
+ how DNS queries are perfomed. See this guide on [DNS caching](/docs/guides/dns-cache.html).
+ The following sub-keys are available:
+
+ * `node_ttl` - By default, this is "0s", which means all node lookups are served with
+ a 0 TTL value. This can be set to allow node lookups to set a TTL value, which enables
+ DNS caching. 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 specified and is used when
+ there is no specific policy available for a service. By default, all services are served
+ with a 0 TTL value. Setting this enables DNS caching.
+
+ * `allow_stale` - Enables a stale query for DNS information. This allows any Consul
+ server to service the request, instead of only the leader. The advantage of this is
+ you get linear read scalability with Consul servers. By default, this is false, meaning
+ all requests are serviced by the leader. This provides stronger consistency but
+ with less throughput and higher latency.
+
+ * `max_stale` - When `allow_stale` is specified, this is used to limit how
+ stale of a result will be used. By default, this is set to "5s", which means
+ if a Consul server is more than 5 seconds behind the leader, the query will be
+ re-evaluated on the leader to get more up-to-date results.
+
* `enable_debug` - When set, enables some additional debugging features. Currently,
only used to set the runtime profiling HTTP endpoints.
@@ -201,12 +225,12 @@ definitions support being updated during a reload.
* `ports` - This is a nested object that allows setting the bind ports
for the following keys:
- * dns - The DNS server, -1 to disable. Default 8600.
- * http - The HTTP api, -1 to disable. Default 8500.
- * rpc - The RPC endpoint. Default 8400.
- * serf_lan - The Serf LAN port. Default 8301.
- * serf_wan - The Serf WAN port. Default 8302.
- * server - Server RPC address. Default 8300.
+ * `dns` - The DNS server, -1 to disable. Default 8600.
+ * `http` - The HTTP api, -1 to disable. Default 8500.
+ * `rpc` - The RPC endpoint. Default 8400.
+ * `serf_lan` - The Serf LAN port. Default 8301.
+ * `serf_wan` - The Serf WAN port. Default 8302.
+ * `server` - Server RPC address. Default 8300.
* `recursor` - This flag provides an address of an upstream DNS server that is used to
recursively resolve queries if they are not inside the service domain for consul. For example,
diff --git a/website/source/docs/guides/dns-cache.html.markdown b/website/source/docs/guides/dns-cache.html.markdown
new file mode 100644
index 000000000..37d79fc47
--- /dev/null
+++ b/website/source/docs/guides/dns-cache.html.markdown
@@ -0,0 +1,74 @@
+---
+layout: "docs"
+page_title: "DNS Caching"
+sidebar_current: "docs-guides-dns-cache"
+---
+
+# DNS Caching
+
+One of the main interfaces to Consul is DNS. Using DNS is a simple way
+integrate Consul into an existing infrastructure without any high-touch
+integration.
+
+By default, Consul serves all DNS results with a 0 TTL value. This prevents
+any caching. The advantage of this is that each DNS lookup is always re-evaluated
+and the most timely information is served. However this adds a latency hit
+for each lookup and can potentially exhaust the query throughput of a cluster.
+
+For this reason, Consul provides a number of tuning parameters that can
+be used to customize how DNS queries are handled.
+
+## Stale Reads
+
+Stale reads can be used to reduce latency and increase the throughput
+of DNS queries. By default, all reads are serviced by a [single leader node](/docs/internals/consensus.html).
+These reads are strongly consistent but are limited by the throughput
+of a single node. Doing a stale read allows any Consul server to
+service a query, but non-leader nodes may return data that is potentially
+out-of-date. By allowing data to be slightly stale, we get horizontal
+read scalability. Now any Consul server can service the request, so we
+increase throughput by the number of servers in a cluster.
+
+The [settings](/docs/agent/options.html) used to control stale reads
+are `dns_config.allow_stale` which must be set to enable stale reads,
+and `dns_config.max_stale` which limits how stale results are allowed to
+be.
+
+By default, `allow_stale` is disabled meaning no stale results may be served.
+The default for `max_stale` is 5 seconds. This means that is `allow_stale` is
+enabled, we will use data from any Consul server that is within 5 seconds
+of the leader.
+
+## TTL Values
+
+TTL values can be set to allow DNS results to be cached upstream
+of Consul which can be reduce the number of lookups and to amortize
+the latency of doing a DNS lookup. By default, all TTLs are zero,
+preventing any caching.
+
+To enable caching of node lookups (e.g. "foo.node.consul"), we can set
+the `dns_config.node_ttl` value. This can be set to "10s" for example,
+and all node lookups will serve results with a 10 second TTL.
+
+Service TTLs can be specified at a more fine grain level. You can set
+a TTL on a per-service level, and additionally a wildcard can be specified
+that matches if there is no specific service TTL provided.
+
+This is specified using the `dns_config.service_ttl` map. The "*" service
+is the wildcard service. For example, if we specify:
+
+```
+ {
+ "dns_config": {
+ "service_ttl": {
+ "*": "5s",
+ "web": "30s"
+ }
+ }
+ }
+```
+
+This sets all lookups to "web.service.consul" to use a 30 second TTL,
+while lookups to "db.service.consul" or "api.service.consul" will use the
+5 second TTL from the wildcard.
+
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index 3d6c84808..7af4ba6a0 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -136,6 +136,10 @@
Bootstrapping
+ >
+ DNS Caching
+
+
>
DNS Forwarding