From 7db70cfcb6367ddacd112aeec5c75d01b060097b Mon Sep 17 00:00:00 2001
From: Sean Chittenden <sean@chittenden.org>
Date: Tue, 2 Feb 2016 15:06:25 -0800
Subject: [PATCH] Iterate on the DNS forwarding docs

Specifically:

* add Dnsmasq examples for reverse DNS for most of the RFC1918, 5735, and 6598 netblocks.
* Highlight some example options for dnsmasq that are probably of interest.
* Add a small section on reverse DNS testing
* Break out BINDs troubleshooting with Dnsmasq's troubleshooting

Not an exhaustive sweep, but should be helpful when introducing consul to new environments.
---
 .../docs/guides/forwarding.html.markdown      | 87 +++++++++++++++++--
 1 file changed, 82 insertions(+), 5 deletions(-)

diff --git a/website/source/docs/guides/forwarding.html.markdown b/website/source/docs/guides/forwarding.html.markdown
index dc0e18befc..19fa22df86 100644
--- a/website/source/docs/guides/forwarding.html.markdown
+++ b/website/source/docs/guides/forwarding.html.markdown
@@ -73,13 +73,56 @@ DNS on port 8600.
 
 ### Dnsmasq Setup
 
-Dnsmasq is typically configured via files in the `/etc/dnsmasq.d` directory.  To configure Consul, create the file `/etc/dnsmasq.d/10-consul` with the following contents:
+Dnsmasq is typically configured via a `dnsmasq.conf` or a series of files in
+the `/etc/dnsmasq.d` directory.  In Dnsmasq's configuration file
+(e.g. `/etc/dnsmasq.d/10-consul`), add the following:
 
 ```text
+# Enable forward lookup of the 'consul' domain:
 server=/consul/127.0.0.1#8600
+
+# Uncomment and modify as appropriate to enable reverse DNS lookups for
+# common netblocks found in RFC 1918, 5735, and 6598:
+#rev-server=0.0.0.0/8,127.0.0.1#8600
+#rev-server=10.0.0.0/8,127.0.0.1#8600
+#rev-server=100.64.0.0/10,127.0.0.1#8600
+#rev-server=127.0.0.1/8,127.0.0.1#8600
+#rev-server=169.254.0.0/16,127.0.0.1#8600
+#rev-server=172.16.0.0/12,127.0.0.1#8600
+#rev-server=192.168.0.0/16,127.0.0.1#8600
+#rev-server=224.0.0.0/4,127.0.0.1#8600
+#rev-server=240.0.0.0/4,127.0.0.1#8600
 ```
 
-Once that configuration is created, restart the dnsmasq service.
+Once that configuration is created, restart the `dnsmasq` service.
+
+Additional useful settings in `dnsmasq` to consider include (see
+[`dnsmasq(8)`](http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq-man.html)
+for additional details):
+
+```
+# Accept DNS queries only from hosts whose address is on a local subnet.
+#local-service
+
+# Don't poll /etc/resolv.conf for changes.
+#no-poll
+
+# Don't read /etc/resolv.conf. Get upstream servers only from the command
+# line or the dnsmasq configuration file (see the "server" directive below).
+#no-resolv
+
+# Specify IP address(es) of other DNS servers for queries not handled
+# directly by consul.  There is normally one 'server' entry set for every
+# 'nameserver' parameter found in '/etc/resolv.conf'.  See dnsmasq(8)'s
+# 'server' configuration option for details.
+#server=1.2.3.4
+#server=208.67.222.222
+#server=8.8.8.8
+
+# Set the size of dnsmasq's cache. The default is 150 names. Setting the
+# cache size to zero disables caching.
+#cache-size=65536
+```
 
 ### Testing
 
@@ -107,7 +150,8 @@ master.redis.service.dc-1.consul. 0 IN A 172.31.3.234
 ;; MSG SIZE  rcvd: 76
 ```
 
-Then run the same query against your BIND instance and make sure you get a result:
+Then run the same query against your BIND instance and make sure you get a
+valid result:
 
 ```text
 [root@localhost ~]# dig @localhost -p 53 master.redis.service.dc-1.consul. A
@@ -131,10 +175,40 @@ master.redis.service.dc-1.consul. 0 IN A 172.31.3.234
 ;; MSG SIZE  rcvd: 76
 ```
 
+If desired, verify reverse DNS using the same methodology:
+
+```text
+[root@localhost ~]# dig @127.0.0.1 -p 8600 133.139.16.172.in-addr.arpa. PTR
+
+; <<>> DiG 9.10.3-P3 <<>> @127.0.0.1 -p 8600 133.139.16.172.in-addr.arpa. PTR
+; (1 server found)
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 3713
+;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
+;; WARNING: recursion requested but not available
+
+;; QUESTION SECTION:
+;133.139.16.172.in-addr.arpa.   IN  PTR
+
+;; ANSWER SECTION:
+133.139.16.172.in-addr.arpa. 0  IN  PTR consul1.node.dc1.consul.
+
+;; Query time: 3 msec
+;; SERVER: 127.0.0.1#8600(127.0.0.1)
+;; WHEN: Sun Jan 31 04:25:39 UTC 2016
+;; MSG SIZE  rcvd: 109
+[root@localhost ~]# dig @127.0.0.1 +short -x 172.16.139.133
+consul1.node.dc1.consul.
+```
+
 ### Troubleshooting
 
-If you don't get an answer from BIND but you do get an answer from Consul, your
-best bet is to turn on BIND's query log to see what's happening:
+If you don't get an answer from your DNS server (e.g. BIND, Dnsmasq) but you
+do get an answer from Consul, your best bet is to turn on your DNS server's
+query log to see what's happening.
+
+For BIND:
 
 ```text
 [root@localhost ~]# rndc querylog
@@ -152,3 +226,6 @@ This indicates that DNSSEC is not disabled properly.
 
 If you see errors about network connections, verify that there are no firewall
 or routing problems between the servers running BIND and Consul.
+
+For Dnsmasq, see the `log-queries` configuration option and the `USR1`
+signal.