From 76aa082d5befeb6aa5ed148427fad0ae92589198 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 7a70ef9fa..856fa5964 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 baede06a9ef05dc63ad0326897647233dc69274f 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 856fa5964..809c4f68e 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