diff options
| -rw-r--r-- | plugin/rewrite/README.md | 175 |
1 files changed, 128 insertions, 47 deletions
diff --git a/plugin/rewrite/README.md b/plugin/rewrite/README.md index 65e0e5905..1a6242f61 100644 --- a/plugin/rewrite/README.md +++ b/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` |