Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-12-02 00:24:08 -05:00
Code Issues Packages Projects Releases Wiki Activity

doc: make -f Makefile.doc (#2919)

Browse Source 
mechanical change: create the manual pages.

Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben
2019-06-24 12:37:27 +01:00
committed by Yong Tang
parent e54b784a7e
commit 51cf388da2
36 changed files with 423 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
man/coredns-rewrite.7
View File

@@ -1,18 +1,18 @@
.\" Generated by Mmark Markdown Processer - mmark.nl
.TH "COREDNS-REWRITE" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
.TH "COREDNS-REWRITE" 7 "June 2019" "CoreDNS" "CoreDNS Plugins"
.SH NAME
.SH "NAME"
.PP
\fIrewrite\fP - performs internal message rewriting.
.SH DESCRIPTION
.SH "DESCRIPTION"
.PP
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
.SH "SYNTAX"
.PP
A simplified/easy to digest syntax for \fIrewrite\fP is...
A simplified/easy-to-digest syntax for \fIrewrite\fP is...
.PP
.RS
@@ -28,10 +28,10 @@ rewrite [continue|stop] FIELD [FROM TO|FROM TTL]
.RS
.IP \(en 4
\fB\fCtype\fR - the type field of the request will be rewritten. FROM/TO must be a DNS record type (\fB\fCA\fR, \fB\fCMX\fR, etc);
\fB\fCtype\fR - the type field of the request will be rewritten. FROM/TO must be a DNS record type (\fB\fCA\fR, \fB\fCMX\fR, etc.);
e.g., to rewrite ANY queries to HINFO, use \fB\fCrewrite type ANY HINFO\fR.
.IP \(en 4
\fB\fCclass\fR - the class of the message will be rewritten. FROM/TO must be a DNS class type (\fB\fCIN\fR, \fB\fCCH\fR, or \fB\fCHS\fR) e.g., to rewrite CH queries to IN use \fB\fCrewrite class CH IN\fR.
\fB\fCclass\fR - the class of the message will be rewritten. FROM/TO must be a DNS class type (\fB\fCIN\fR, \fB\fCCH\fR, or \fB\fCHS\fR); e.g., to rewrite CH queries to IN use \fB\fCrewrite class CH IN\fR.
.IP \(en 4
\fB\fCname\fR - the query name in the \fIrequest\fP is rewritten; by default this is a full match of the
name, e.g., \fB\fCrewrite name example.net example.org\fR. Other match types are supported, see the \fBName Field Rewrites\fP section below.
@@ -52,21 +52,24 @@ name, e.g., \fB\fCrewrite name example.net example.org\fR. Other match types are
.PP
If you specify multiple rules and an incoming query matches on multiple rules, the rewrite
will behave as following
* \fB\fCcontinue\fR will continue apply the next rule in the rule list.
* \fB\fCstop\fR will consider the current rule is the last rule and will not continue. Default behaviour
for not specifying this rule processing mode is \fB\fCstop\fR
If you specify multiple rules and an incoming query matches multiple rules, the rewrite
will behave as follows:
.SS NAME FIELD REWRITES
.IP \(bu 4
\fB\fCcontinue\fR will continue applying the next rule in the rule list.
.IP \(bu 4
\fB\fCstop\fR will consider the current rule the last rule and will not continue. The default behaviour is \fB\fCstop\fR
.SS "NAME FIELD REWRITES"
.PP
The \fB\fCrewrite\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. If the newly used name is not a legal domain name the plugin returns an error to the
The \fB\fCrewrite\fR plugin offers the ability to match the name in the question section of
a DNS request. The match could be exact, a substring match, or based on a prefix, suffix, or regular
expression. If the newly used name is not a legal domain name, the plugin returns an error to the
client.
.PP
The syntax for the name re-writing is as follows:
The syntax for name rewriting is as follows:
.PP
.RS
@@ -78,10 +81,10 @@ rewrite [continue|stop] name [exact|prefix|suffix|substring|regex] STRING STRING
.RE
.PP
The match type, i.e. \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers re-write:
The match type, e.g., \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers rewrite:
.IP \(bu 4
\fBexact\fP (default): on exact match of the name in the question section of a request
\fBexact\fP (default): on an exact match of the name in the question section of a request
.IP \(bu 4
\fBsubstring\fP: on a partial match of the name in the question section of a request
.IP \(bu 4
@@ -93,11 +96,11 @@ The match type, i.e. \fB\fCexact\fR, \fB\fCsubstring\fR, etc., triggers re-write
.PP
If the match type is omitted, the \fB\fCexact\fR match type is being assumed.
If the match type is omitted, the \fB\fCexact\fR match type is assumed.
.PP
The following instruction allows re-writing the name in the query that
contains \fB\fCservice.us-west-1.example.org\fR substring.
The following instruction allows rewriting names in the query that
contain the substring \fB\fCservice.us-west-1.example.org\fR:
.PP
.RS
@@ -114,12 +117,12 @@ Thus:
.IP \(bu 4
Incoming Request Name: \fB\fCftp.service.us-west-1.example.org\fR
.IP \(bu 4
Re-written Request Name: \fB\fCftp.service.us-west-1.consul\fR
Rewritten Request Name: \fB\fCftp.service.us-west-1.consul\fR
.PP
The following instruction uses regular expressions. The name in a request
matching \fB\fC(.*)-(us-west-1)\.example\.org\fR regular expression is being replaces with
The following instruction uses regular expressions. Names in requests
matching the regular expression \fB\fC(.*)-(us-west-1)\.example\.org\fR are replaced with
\fB\fC{1}.service.{2}.consul\fR, where \fB\fC{1}\fR and \fB\fC{2}\fR are regular expression match groups.
.PP
@@ -137,7 +140,7 @@ Thus:
.IP \(bu 4
Incoming Request Name: \fB\fCftp-us-west-1.example.org\fR
.IP \(bu 4
Re-written Request Name: \fB\fCftp.service.us-west-1.consul\fR
Rewritten Request Name: \fB\fCftp.service.us-west-1.consul\fR
.PP
@@ -152,11 +155,11 @@ rewrite name suffix .schmoogle.com. .google.com.
.fi
.RE
.SS RESPONSE REWRITES
.SS "RESPONSE REWRITES"
.PP
When re-writing incoming DNS requests' names, CoreDNS re-writes the \fB\fCQUESTION SECTION\fR
section of the requests. It may be necessary to re-write the \fB\fCANSWER SECTION\fR of the
requests, because some DNS resolvers would treat the mismatch between \fB\fCQUESTION SECTION\fR
When rewriting incoming DNS requests' names, CoreDNS re-writes the \fB\fCQUESTION SECTION\fR
section of the requests. It may be necessary to rewrite the \fB\fCANSWER SECTION\fR of the
requests, because some DNS resolvers treat mismatches between the \fB\fCQUESTION SECTION\fR
and \fB\fCANSWER SECTION\fR as a man-in-the-middle attack (MITM).
.PP
@@ -173,9 +176,9 @@ rewrite name regex (.*)\-(us\-west\-1)\\.coredns\\.rocks {1}.service.{2}.consul
.RE
.PP
CoreDNS instance re-wrote the request to \fB\fCftp-us-west-1.coredns.rocks\fR with
CoreDNS rewrote the request from \fB\fCftp-us-west-1.coredns.rocks\fR to
\fB\fCftp.service.us-west-1.consul\fR and ultimately resolved it to 3 records.
The resolved records, see \fB\fCANSWER SECTION\fR, were not from \fB\fCcoredns.rocks\fR, but
The resolved records, in the \fB\fCANSWER SECTION\fR below, were not from \fB\fCcoredns.rocks\fR, but
rather from \fB\fCservice.us-west-1.consul\fR.
.PP
@@ -203,11 +206,11 @@ ftp.service.us\-west\-1.consul. 0 IN A 10.30.30.30
.RE
.PP
The above is the mismatch.
The above is a mismatch between the question asked and the answer provided.
.PP
The following configuration snippet allows for the re-writing of the
\fB\fCANSWER SECTION\fR, provided that the \fB\fCQUESTION SECTION\fR was re-written:
The following configuration snippet allows for rewriting of the
\fB\fCANSWER SECTION\fR, provided that the \fB\fCQUESTION SECTION\fR was rewritten:
.PP
.RS
@@ -264,14 +267,14 @@ rewrite [continue|stop] {
.RE
.PP
Note that the above syntax is strict. For response rewrites only \fB\fCname\fR
Note that the above syntax is strict. For response rewrites, only \fB\fCname\fR
rules are allowed to match the question section, and only by match type
\fB\fCregex\fR. The answer rewrite must be after the name, as ordered in the
\fB\fCregex\fR. The answer rewrite must be after the name, as in the
syntax example. There must only be two lines (a \fB\fCname\fR followed by an
\fB\fCanswer\fR) in the brackets, additional rules are not supported.
\fB\fCanswer\fR) in the brackets; additional rules are not supported.
.PP
An alternate syntax for the rewrite of DNS request and response is as
An alternate syntax for rewriting a DNS request and response is as
follows:
.PP
@@ -284,8 +287,8 @@ rewrite [continue|stop] name regex STRING STRING answer name STRING STRING
.RE
.PP
When using \fB\fCexact\fR name rewrite rules, answer gets re-written automatically,
and there is no need defining \fB\fCanswer name\fR instruction. The below rule
When using \fB\fCexact\fR name rewrite rules, the answer gets rewritten automatically,
and there is no need to define \fB\fCanswer name\fR. The rule below
rewrites the name in a request from \fB\fCRED\fR to \fB\fCBLUE\fR, and subsequently
rewrites the name in a corresponding response from \fB\fCBLUE\fR to \fB\fCRED\fR. The
client in the request would see only \fB\fCRED\fR and no \fB\fCBLUE\fR.
@@ -299,11 +302,11 @@ rewrite [continue|stop] name exact RED BLUE
.fi
.RE
.SS TTL FIELD REWRITES
.SS "TTL FIELD REWRITES"
.PP
At times, the need for rewriting TTL value could arise. For example, a DNS server
may prevent caching by setting TTL as low as zero (\fB\fC0\fR). An administrator
may want to increase the TTL to prevent caching, e.g. to 15 seconds.
At times, the need to rewrite a TTL value could arise. For example, a DNS server
may not cache records with a TTL of zero (\fB\fC0\fR). An administrator
may want to increase the TTL to ensure it is cached, e.g., by increasing it to 15 seconds.
.PP
In the below example, the TTL in the answers for \fB\fCcoredns.rocks\fR domain are
@@ -321,8 +324,8 @@ being set to \fB\fC15\fR:
.RE
.PP
By the same token, an administrator may use this feature to force caching by
setting TTL value really low.
By the same token, an administrator may use this feature to prevent or limit caching by
setting the TTL value really low.
.PP
The syntax for the TTL rewrite rule is as follows. The meaning of
@@ -337,9 +340,9 @@ rewrite [continue|stop] ttl [exact|prefix|suffix|substring|regex] STRING SECONDS
.fi
.RE
.SH EDNS0 OPTIONS
.SH "EDNS0 OPTIONS"
.PP
Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the request.
Using the FIELD edns0, you can set, append, or replace specific EDNS0 options in the request.
.IP \(bu 4
\fB\fCreplace\fR will modify any "matching" option with the specified option. The criteria for "matching" varies based on EDNS0 type.
@@ -352,12 +355,12 @@ Using FIELD edns0, you can set, append, or replace specific EDNS0 options on the
.PP
Currently supported are \fB\fCEDNS0_LOCAL\fR, \fB\fCEDNS0_NSID\fR and \fB\fCEDNS0_SUBNET\fR.
.SS EDNS0_LOCAL
.SS "EDNS0_LOCAL"
.PP
This has two fields, code and data. A match is defined as having the same code. Data may be a string or a variable.
.IP \(bu 4
A string data can be treated as hex if it starts with \fB\fC0x\fR. Example:
A string data is treated as hex if it starts with \fB\fC0x\fR. Example:
.PP
@@ -373,7 +376,7 @@ A string data can be treated as hex if it starts with \fB\fC0x\fR. Example:
.RE
.PP
rewrites the first local option with code 0xffee, setting the data to "abcd". Equivalent:
rewrites the first local option with code 0xffee, setting the data to "abcd". This is equivalent to:
.PP
.RS
@@ -391,8 +394,8 @@ A variable data is specified with a pair of curly brackets \fB\fC{}\fR. Followin
{qname}, {qtype}, {client\fIip}, {client\fPport}, {protocol}, {server\fIip}, {server\fPport}.
.IP \(bu 4
If the metadata plugin is enabled, then labels are supported as variables if they are presented within curly brackets.
the variable data will be filled with the value associated with that label. If that label is not provided,
the variable will be silently substitute by an empty string.
The variable data will be replaced with the value associated with that label. If that label is not provided,
the variable will be silently substituted with an empty string.
.PP
@@ -421,12 +424,12 @@ rewrite edns0 local set 0xffee {some\-plugin/some\-label}
.fi
.RE
.SS EDNS0_NSID
.SS "EDNS0_NSID"
.PP
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 \fB\fCreplace\fR or \fB\fCset\fR, then the NSID in the option will be set to the empty string.
.SS EDNS0_SUBNET
.SS "EDNS0_SUBNET"
.PP
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.
@@ -444,12 +447,12 @@ rewrite edns0 subnet set 24 56
.RE
.IP \(bu 4
If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet.
If the query's source IP address is an IPv4 address, 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.
If the query's source IP address is an IPv6 address, the first 56 bits in the IP will be the network subnet.
.SH FULL SYNTAX
.SH "FULL SYNTAX"
.PP
The full plugin usage syntax is harder to digest...
@@ -463,5 +466,5 @@ rewrite [continue|stop] {type|class|edns0|name [exact|prefix|suffix|substring|re
.RE
.PP
The syntax above doesn't cover the multi line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fP section.
The syntax above doesn't cover the multi-line block option for specifying a name request+response rewrite rule described in the \fBResponse Rewrite\fP section.