Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-11-02 10:13:14 -05:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Paul Greenberg
2018-01-22 22:01:13 -05:00
committed by John Belamaric
parent d4bf076ccf
commit 7d371edb2d
1 changed files with 128 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
plugin/rewrite/README.md
View File

@@ -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`