335 lines
8.5 KiB
Groff
335 lines
8.5 KiB
Groff
.\" generated with Ronn/v0.7.3
|
|
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
|
.
|
|
.TH "COREDNS\-REWRITE" "7" "February 2018" "CoreDNS" "CoreDNS plugins"
|
|
.
|
|
.SH "NAME"
|
|
\fIrewrite\fR \- performs internal message rewriting\.
|
|
.
|
|
.SH "DESCRIPTION"
|
|
Rewrites are invisible to the client\. There are simple rewrites (fast) and complex rewrites (slower), but they\'re powerful enough to accommodate most dynamic back\-end applications\.
|
|
.
|
|
.SH "SYNTAX"
|
|
.
|
|
.nf
|
|
|
|
rewrite [continue|stop] FIELD FROM TO
|
|
.
|
|
.fi
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBFIELD\fR is (\fBtype\fR, \fBclass\fR, \fBname\fR, \.\.\.)
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBFROM\fR is the exact name of type to match
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBTO\fR is the destination name or type to rewrite to
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
When the FIELD is \fBtype\fR and FROM is (\fBA\fR, \fBMX\fR, etc\.), the type of the message will be rewritten; e\.g\., to rewrite ANY queries to HINFO, use \fBrewrite type ANY HINFO\fR\.
|
|
.
|
|
.P
|
|
When the FIELD is \fBclass\fR and FROM is (\fBIN\fR, \fBCH\fR, or \fBHS\fR) the class of the message will be rewritten; e\.g\., to rewrite CH queries to IN use \fBrewrite class CH IN\fR\.
|
|
.
|
|
.P
|
|
When the FIELD is \fBname\fR the query name in the message is rewritten; this needs to be a full match of the name, e\.g\., \fBrewrite name miek\.nl example\.org\fR\.
|
|
.
|
|
.P
|
|
When the FIELD is \fBedns0\fR an EDNS0 option can be appended to the request as described below\.
|
|
.
|
|
.P
|
|
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite will behave as following * \fBcontinue\fR will continue apply the next rule in the rule list\. * \fBstop\fR will consider the current rule is the last rule and will not continue\. Default behaviour for not specifying this rule processing mode is \fBstop\fR
|
|
.
|
|
.SS "NAME FIELD REWRITES"
|
|
The \fBrewrite\fR 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\.
|
|
.
|
|
.P
|
|
The syntax for the name re\-writing is as follows:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
The match type, i\.e\. \fBexact\fR, \fBsubstring\fR, etc\., triggers re\-write:
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBexact\fR (default): on exact match of the name in the question section of a request
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBsubstring\fR: on a partial match of the name in the question section of a request
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBprefix\fR: when the name begins with the matching string
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBsuffix\fR: when the name ends with the matching string
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBregex\fR: when the name in the question section of a request matches a regular expression
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
If the match type is omitted, the \fBexact\fR match type is being assumed\.
|
|
.
|
|
.P
|
|
The following instruction allows re\-writing the name in the query that contains \fBservice\.us\-west\-1\.example\.org\fR substring\.
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite name substring service\.us\-west\-1\.example\.org service\.us\-west\-1\.consul
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Thus:
|
|
.
|
|
.IP "\(bu" 4
|
|
Incoming Request Name: \fBftp\.service\.us\-west\-1\.example\.org\fR
|
|
.
|
|
.IP "\(bu" 4
|
|
Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
The following instruction uses regular expressions\. The name in a request matching \fB(\.*)\-(us\-west\-1)\e\.example\e\.org\fR regular expression is being replaces with \fB{1}\.service\.{2}\.consul\fR, where \fB{1}\fR and \fB{2}\fR are regular expression match groups\.
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite name regex (\.*)\-(us\-west\-1)\e\.example\e\.org {1}\.service\.{2}\.consul
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Thus:
|
|
.
|
|
.IP "\(bu" 4
|
|
Incoming Request Name: \fBftp\-us\-west\-1\.example\.org\fR
|
|
.
|
|
.IP "\(bu" 4
|
|
Re\-written Request Name: \fBftp\.service\.us\-west\-1\.consul\fR
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SS "RESPONSE REWRITES"
|
|
When re\-writing incoming DNS requests\' names, CoreDNS re\-writes the \fBQUESTION SECTION\fR section of the requests\. It may be necessary to re\-write the \fBANSWER SECTION\fR of the requests, because some DNS resolvers would treat the mismatch between \fBQUESTION SECTION\fR and \fBANSWER SECTION\fR as a man\-in\-the\-middle attack (MITM)\.
|
|
.
|
|
.P
|
|
For example, a user tries to resolve \fBftp\-us\-west\-1\.coredns\.rocks\fR\. The CoreDNS configuration file has the following rule:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
CoreDNS instance re\-wrote the request to \fBftp\-us\-west\-1\.coredns\.rocks\fR with \fBftp\.service\.us\-west\-1\.consul\fR and ultimately resolved it to 3 records\. The resolved records, see \fBANSWER SECTION\fR, were not from \fBcoredns\.rocks\fR, but rather from \fBservice\.us\-west\-1\.consul\fR\.
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
$ 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
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
The above is the mismatch\.
|
|
.
|
|
.P
|
|
The following configuration snippet allows for the re\-writing of the \fBANSWER SECTION\fR, provided that the \fBQUESTION SECTION\fR was re\-written:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite stop {
|
|
name regex (\.*)\-(us\-west\-1)\e\.coredns\e\.rocks {1}\.service\.{2}\.consul
|
|
answer name (\.*)\e\.service\e\.(us\-west\-1)\e\.consul {1}\-{2}\.coredns\.rocks
|
|
}
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Now, the \fBANSWER SECTION\fR matches the \fBQUESTION SECTION\fR:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
$ 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
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
The syntax for the response of DNS request and response is as follows:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite [continue|stop] {
|
|
name regex STRING STRING
|
|
answer name STRING STRING
|
|
}
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SH "EDNS0 OPTIONS"
|
|
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request\.
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBreplace\fR will modify any matching (what that means may vary based on EDNS0 type) option with the specified option
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBappend\fR will add the option regardless of what options already exist
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBset\fR will modify a matching option or add one if none is found
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Currently supported are \fBEDNS0_LOCAL\fR, \fBEDNS0_NSID\fR and \fBEDNS0_SUBNET\fR\.
|
|
.
|
|
.SS "EDNS0_LOCAL"
|
|
This has two fields, code and data\. A match is defined as having the same code\. Data may be a string or a variable\.
|
|
.
|
|
.TP
|
|
A string data can be treated as hex if it starts with \fB0x\fR\. Example:
|
|
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
\&\. {
|
|
rewrite edns0 local set 0xffee 0x61626364
|
|
whoami
|
|
}
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
rewrites the first local option with code 0xffee, setting the data to "abcd"\. Equivalent:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
\&\. {
|
|
rewrite edns0 local set 0xffee abcd
|
|
}
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.TP
|
|
A variable data is specified with a pair of curly brackets \fB{}\fR\. Following are the supported variables
|
|
{qname}, {qtype}, {client_ip}, {client_port}, {protocol}, {server_ip}, {server_port}\.
|
|
.
|
|
.P
|
|
Example:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite edns0 local set 0xffee {client_ip}
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SS "EDNS0_NSID"
|
|
This has no fields; it will add an NSID option with an empty string for the NSID\. If the option already exists and the action is \fBreplace\fR or \fBset\fR, then the NSID in the option will be set to the empty string\.
|
|
.
|
|
.SS "EDNS0_SUBNET"
|
|
This has two fields, IPv4 bitmask length and IPv6 bitmask length\. The bitmask length is used to extract the client subnet from the source IP address in the query\.
|
|
.
|
|
.P
|
|
Example:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
rewrite edns0 subnet set 24 56
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.IP "\(bu" 4
|
|
If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet\.
|
|
.
|
|
.IP "\(bu" 4
|
|
If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet\.
|
|
.
|
|
.IP "" 0
|
|
|