plugin/rewrite: add response rewrite docs (#1414)

plugin/rewrite/README.md

@@ -36,6 +36,134 @@ will behave as following
 * `stop` will consider the current rule is the last rule and will not continue.  Default behaviour
 for not specifying this rule processing mode is `stop`
 
+### Name Field Rewrites
+
+The `rewrite` plugin offers the ability to match on the name in the question section of
+a DNS request. The match could be exact, substring, or based on a prefix, suffix, or regular
+expression.
+
+The syntax for the name re-writing is as follows:
+
+```
+rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
+```
+
+The match type, i.e. `exact`, `substring`, etc., triggers re-write:
+
+* **exact** (default): on exact match of the name in the question section of a request
+* **substring**: on a partial match of the name in the question section of a request
+* **prefix**: when the name begins with the matching string
+* **suffix**: when the name ends with the matching string
+* **regex**: when the name in the question section of a request matches a regular expression
+
+If the match type is omitted, the `exact` match type is being assumed.
+
+The following instruction allows re-writing the name in the query that
+contains `service.us-west-1.example.org` substring.
+
+```
+rewrite name substring service.us-west-1.example.org service.us-west-1.consul
+```
+
+Thus:
+
+* Incoming Request Name: `ftp.service.us-west-1.example.org`
+* Re-written Request Name: `ftp.service.us-west-1.consul`
+
+The following instruction uses regular expressions. The name in a request
+matching `(.*)-(us-west-1)\.example\.org` regular expression is being replaces with
+`{1}.service.{2}.consul`, where `{1}` and `{2}` are regular expression match groups.
+
+```
+rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul
+```
+
+Thus:
+
+* Incoming Request Name: `ftp-us-west-1.example.org`
+* Re-written Request Name: `ftp.service.us-west-1.consul`
+
+### Response Rewrites
+
+When re-writing incoming DNS requests' names, CoreDNS re-writes the `QUESTION SECTION`
+section of the requests. It may be necessary to re-write the `ANSWER SECTION` of the
+requests, because some DNS resolvers would treat the mismatch between `QUESTION SECTION`
+and `ANSWER SECTION` as a man-in-the-middle attack (MITM).
+
+For example, a user tries to resolve `ftp-us-west-1.coredns.rocks`. The
+CoreDNS configuration file has the following rule:
+
+```
+rewrite name regex (.*)-(us-west-1)\.coredns\.rocks {1}.service.{2}.consul
+```
+
+CoreDNS instance re-wrote the request to `ftp-us-west-1.coredns.rocks` with
+`ftp.service.us-west-1.consul` and ultimately resolved it to 3 records.
+The resolved records, see `ANSWER SECTION`, were not from `coredns.rocks`, but
+rather from `service.us-west-1.consul`.
+
+
+```
+$ dig @10.1.1.1 ftp-us-west-1.coredns.rocks
+
+; <<>> DiG 9.8.3-P1 <<>> @10.1.1.1 ftp-us-west-1.coredns.rocks
+; (1 server found)
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 8619
+;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
+
+;; QUESTION SECTION:
+;ftp-us-west-1.coredns.rocks. IN A
+
+;; ANSWER SECTION:
+ftp.service.us-west-1.consul. 0    IN A    10.10.10.10
+ftp.service.us-west-1.consul. 0    IN A    10.20.20.20
+ftp.service.us-west-1.consul. 0    IN A    10.30.30.30
+```
+
+The above is the mismatch.
+
+The following configuration snippet allows for the re-writing of the
+`ANSWER SECTION`, provided that the `QUESTION SECTION` was re-written:
+
+```
+    rewrite stop {
+        name regex (.*)-(us-west-1)\.coredns\.rocks {1}.service.{2}.consul
+        answer name (.*)\.service\.(us-west-1)\.consul {1}-{2}.coredns.rocks
+    }
+```
+
+Now, the `ANSWER SECTION` matches the `QUESTION SECTION`:
+
+```
+$ dig @10.1.1.1 ftp-us-west-1.coredns.rocks
+
+; <<>> DiG 9.8.3-P1 <<>> @10.1.1.1 ftp-us-west-1.coredns.rocks
+; (1 server found)
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 8619
+;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0
+
+;; QUESTION SECTION:
+;ftp-us-west-1.coredns.rocks. IN A
+
+;; ANSWER SECTION:
+ftp-us-west-1.coredns.rocks. 0    IN A    10.10.10.10
+ftp-us-west-1.coredns.rocks. 0    IN A    10.20.20.20
+ftp-us-west-1.coredns.rocks. 0    IN A    10.30.30.30
+```
+
+The syntax for the response of DNS request and response is as follows:
+
+```
+rewrite [continue|stop] {
+    name regex STRING STRING
+    answer name STRING STRING
+}
+```
+
 ## EDNS0 Options
 
 Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request.
@@ -94,50 +222,3 @@ rewrite edns0 subnet set 24 56
 
 * If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet.
 * If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet.
-
-### Name Field Rewrites
-
-The `rewrite` plugin offers the ability to match on the name in the question section of
-a DNS request. The match could be exact, substring, or based on a prefix, suffix, or regular
-expression.
-
-The syntax for the name re-writing is as follows:
-
-```
-rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
-```
-
-The match type, i.e. `exact`, `substring`, etc., triggers re-write:
-
-* **exact** (default): on exact match of the name in the question section of a request
-* **substring**: on a partial match of the name in the question section of a request
-* **prefix**: when the name begins with the matching string
-* **suffix**: when the name ends with the matching string
-* **regex**: when the name in the question section of a request matches a regular expression
-
-If the match type is omitted, the `exact` match type is being assumed.
-
-The following instruction allows re-writing the name in the query that
-contains `service.us-west-1.example.org` substring.
-
-```
-rewrite name substring service.us-west-1.example.org service.us-west-1.consul
-```
-
-Thus:
-
-* Incoming Request Name: `ftp.service.us-west-1.example.org`
-* Re-written Request Name: `ftp.service.us-west-1.consul`
-
-The following instruction uses regular expressions. The name in a request
-matching `(.*)-(us-west-1)\.example\.org` regular expression is being replaces with
-`{1}.service.{2}.consul`, where `{1}` and `{2}` are regular expression match groups.
-
-```
-rewrite name regex (.*)-(us-west-1)\.example\.org {1}.service.{2}.consul
-```
-
-Thus:
-
-* Incoming Request Name: `ftp-us-west-1.example.org`
-* Re-written Request Name: `ftp.service.us-west-1.consul`