From b71a51e27778ad7cde5e34026e9f77763b1992a8 Mon Sep 17 00:00:00 2001 From: Marc Tamsky Date: Fri, 28 Aug 2015 18:10:37 -0700 Subject: [PATCH 1/2] add dnsmasq example, add pointer to 'recursors' --- .../source/docs/guides/forwarding.html.markdown | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/website/source/docs/guides/forwarding.html.markdown b/website/source/docs/guides/forwarding.html.markdown index 7a70ef9fa8..856fa59645 100644 --- a/website/source/docs/guides/forwarding.html.markdown +++ b/website/source/docs/guides/forwarding.html.markdown @@ -13,10 +13,15 @@ requires elevated privileges. Instead of running Consul with an administrative or root account, it is possible to instead forward appropriate queries to Consul, running on an unprivileged port, from another DNS server. -In this guide, we will demonstrate forwarding from [BIND](https://www.isc.org/downloads/bind/). +In this guide, we will demonstrate forwarding from [BIND](https://www.isc.org/downloads/bind/), +as well as [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html). For the sake of simplicity, BIND and Consul are running on the same machine in this example, but this is not required. +Additionally, by default, consul will not attempt to resolve CNAME records outside the `.consul.` +zone, unless the [recursors](/docs/agent/options.html#recursors) configuration +option is set. + ### BIND Setup First, you have to disable DNSSEC so that Consul and BIND can communicate. @@ -60,6 +65,15 @@ zone "consul" IN { Here we assume Consul is running with default settings and is serving DNS on port 8600. +### Dnsmasq + +Add the following to your config. Typically `/etc/dnsmasq.d/` is enabled which should allow creation of a file `/etc/dnsmasq.d/10-consul`: +```text +server=/consul/127.0.0.1#8600 +``` +restart the dnsmasq process after making configuration changes. + + ### Testing First, perform a DNS query against Consul directly to be sure that the record exists: From 0db9346ecc649d2bef3bbff1cbb7881aa0637338 Mon Sep 17 00:00:00 2001 From: Marc Tamsky Date: Fri, 28 Aug 2015 18:27:26 -0700 Subject: [PATCH 2/2] Explain 'recursors' behavior with an example. --- website/source/docs/guides/forwarding.html.markdown | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/website/source/docs/guides/forwarding.html.markdown b/website/source/docs/guides/forwarding.html.markdown index 856fa59645..809c4f68e9 100644 --- a/website/source/docs/guides/forwarding.html.markdown +++ b/website/source/docs/guides/forwarding.html.markdown @@ -18,9 +18,15 @@ as well as [dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html). For the sake of simplicity, BIND and Consul are running on the same machine in this example, but this is not required. -Additionally, by default, consul will not attempt to resolve CNAME records outside the `.consul.` -zone, unless the [recursors](/docs/agent/options.html#recursors) configuration -option is set. +It is worth mentioning that, by default, consul does not resolve DNS +records outside the `.consul.` zone, unless the +[recursors](/docs/agent/options.html#recursors) configuration option +has been set. An example of how this changes consul's behavior is: +When a consul DNS reply includes a CNAME record pointing outside +`.consul.` the DNS reply includes only CNAME records. +Contrastingly, when `recursors` is set and the upstream resolver is +functioning correctly, consul will try to resolve CNAMEs and include +any A/PTR records for them in its DNS reply. ### BIND Setup