mirror of
https://github.com/coredns/coredns.git
synced 2025-10-27 00:04:15 -04:00
docs: Regenerate all manpages using mmark (#2762)
Mmark recently became able to create manual pages. This removed the dependency on 'ronn' and just uses mmark (Go program). Re-hookup Makefile.doc to generate the correct header mmark needs to see and regenate them all. Spot checking a few pages suggest they look good and actually better than rendered with ronn, esp. lists in lists. Fixes #2757 Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben
GitHub
@@ -1,207 +1,206 @@
|
||||
.\" generated with Ronn/v0.7.3
|
||||
.\" http://github.com/rtomayko/ronn/tree/0.7.3
|
||||
.
|
||||
.TH "COREDNS\-GRPC" "7" "March 2019" "CoreDNS" "CoreDNS plugins"
|
||||
.
|
||||
.SH "NAME"
|
||||
\fIgrpc\fR \- facilitates proxying DNS messages to upstream resolvers via gRPC protocol\.
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
The \fIgrpc\fR plugin supports gRPC and TLS\.
|
||||
.
|
||||
.P
|
||||
This plugin can only be used once per Server Block\.
|
||||
.
|
||||
.SH "SYNTAX"
|
||||
.\" Generated by Mmark Markdown Processer - mmark.nl
|
||||
.TH "COREDNS-GRPC" "7" "April 2019" "CoreDNS" "CoreDNS Plugins"
|
||||
|
||||
.SH GRPC
|
||||
.SH NAME
|
||||
.PP
|
||||
\fIgrpc\fP - facilitates proxying DNS messages to upstream resolvers via gRPC protocol.
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The \fIgrpc\fP plugin supports gRPC and TLS.
|
||||
|
||||
.PP
|
||||
This plugin can only be used once per Server Block.
|
||||
|
||||
.SH SYNTAX
|
||||
.PP
|
||||
In its most basic form:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
grpc FROM TO\.\.\.
|
||||
.
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
grpc FROM TO...
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBFROM\fR is the base domain to match for the request to be proxied\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBTO\.\.\.\fR are the destination endpoints to proxy to\. The number of upstreams is limited to 15\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Multiple upstreams are randomized (see \fBpolicy\fR) on first use\. When a proxy returns an error the next upstream in the list is tried\.
|
||||
.
|
||||
.P
|
||||
.RE
|
||||
|
||||
.IP \(bu 4
|
||||
\fBFROM\fP is the base domain to match for the request to be proxied.
|
||||
.IP \(bu 4
|
||||
\fBTO...\fP are the destination endpoints to proxy to. The number of upstreams is
|
||||
limited to 15.
|
||||
|
||||
|
||||
.PP
|
||||
Multiple upstreams are randomized (see \fB\fCpolicy\fR) on first use. When a proxy returns an error
|
||||
the next upstream in the list is tried.
|
||||
|
||||
.PP
|
||||
Extra knobs are available with an expanded syntax:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
grpc FROM TO\.\.\. {
|
||||
except IGNORED_NAMES\.\.\.
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
grpc FROM TO... {
|
||||
except IGNORED\_NAMES...
|
||||
tls CERT KEY CA
|
||||
tls_servername NAME
|
||||
policy random|round_robin|sequential
|
||||
tls\_servername NAME
|
||||
policy random|round\_robin|sequential
|
||||
}
|
||||
.
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBFROM\fR and \fBTO\.\.\.\fR as above\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBIGNORED_NAMES\fR in \fBexcept\fR is a space\-separated list of domains to exclude from proxying\. Requests that match none of these names will be passed through\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR define the TLS properties for TLS connection\. From 0 to 3 arguments can be provided with the meaning as described below
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \- no client authentication is used, and the system CAs are used to verify the server certificate
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCA\fR \- no client authentication is used, and the file CA is used to verify the server certificate
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified with the system CAs
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls\fR \fBCERT\fR \fBKEY\fR \fBCA\fR \- client authentication is used with the specified cert/key pair\. The server certificate is verified using the specified CA file
|
||||
.
|
||||
.IP "" 0
|
||||
.RE
|
||||
|
||||
.IP \(bu 4
|
||||
\fBFROM\fP and \fBTO...\fP as above.
|
||||
.IP \(bu 4
|
||||
\fBIGNORED_NAMES\fP in \fB\fCexcept\fR is a space-separated list of domains to exclude from proxying.
|
||||
Requests that match none of these names will be passed through.
|
||||
.IP \(bu 4
|
||||
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP define the TLS properties for TLS connection. From 0 to 3 arguments can be
|
||||
provided with the meaning as described below
|
||||
|
||||
.RS
|
||||
.IP \(en 4
|
||||
\fB\fCtls\fR - no client authentication is used, and the system CAs are used to verify the server certificate
|
||||
.IP \(en 4
|
||||
\fB\fCtls\fR \fBCA\fP - no client authentication is used, and the file CA is used to verify the server certificate
|
||||
.IP \(en 4
|
||||
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP - client authentication is used with the specified cert/key pair.
|
||||
The server certificate is verified with the system CAs
|
||||
.IP \(en 4
|
||||
\fB\fCtls\fR \fBCERT\fP \fBKEY\fP \fBCA\fP - client authentication is used with the specified cert/key pair.
|
||||
The server certificate is verified using the specified CA file
|
||||
|
||||
.RE
|
||||
.IP \(bu 4
|
||||
\fB\fCtls_servername\fR \fBNAME\fP allows you to set a server name in the TLS configuration; for instance 9.9.9.9
|
||||
needs this to be set to \fB\fCdns.quad9.net\fR. Multiple upstreams are still allowed in this scenario,
|
||||
but they have to use the same \fB\fCtls_servername\fR. E.g. mixing 9.9.9.9 (QuadDNS) with 1.1.1.1
|
||||
(Cloudflare) will not work.
|
||||
.IP \(bu 4
|
||||
\fB\fCpolicy\fR specifies the policy to use for selecting upstream servers. The default is \fB\fCrandom\fR.
|
||||
|
||||
|
||||
.PP
|
||||
Also note the TLS config is "global" for the whole grpc proxy if you need a different
|
||||
\fB\fCtls-name\fR for different upstreams you're out of luck.
|
||||
|
||||
.SH METRICS
|
||||
.PP
|
||||
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric are exported:
|
||||
|
||||
.IP \(bu 4
|
||||
\fB\fCcoredns_grpc_request_duration_seconds{to}\fR - duration per upstream interaction.
|
||||
.IP \(bu 4
|
||||
\fB\fCcoredns_grpc_request_count_total{to}\fR - query count per upstream.
|
||||
.IP \(bu 4
|
||||
\fB\fCcoredns_grpc_response_rcode_total{to, rcode}\fR - count of RCODEs per upstream.
|
||||
and we are randomly (this always uses the \fB\fCrandom\fR policy) spraying to an upstream.
|
||||
|
||||
|
||||
.SH EXAMPLES
|
||||
.PP
|
||||
Proxy all requests within \fB\fCexample.org.\fR to a nameserver running on a different port:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBtls_servername\fR \fBNAME\fR allows you to set a server name in the TLS configuration; for instance 9\.9\.9\.9 needs this to be set to \fBdns\.quad9\.net\fR\. Multiple upstreams are still allowed in this scenario, but they have to use the same \fBtls_servername\fR\. E\.g\. mixing 9\.9\.9\.9 (QuadDNS) with 1\.1\.1\.1 (Cloudflare) will not work\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBpolicy\fR specifies the policy to use for selecting upstream servers\. The default is \fBrandom\fR\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Also note the TLS config is "global" for the whole grpc proxy if you need a different \fBtls\-name\fR for different upstreams you\'re out of luck\.
|
||||
.
|
||||
.SH "METRICS"
|
||||
If monitoring is enabled (via the \fIprometheus\fR directive) then the following metric are exported:
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_grpc_request_duration_seconds{to}\fR \- duration per upstream interaction\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_grpc_request_count_total{to}\fR \- query count per upstream\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBcoredns_grpc_response_rcode_total{to, rcode}\fR \- count of RCODEs per upstream\. and we are randomly (this always uses the \fBrandom\fR policy) spraying to an upstream\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Proxy all requests within \fBexample\.org\.\fR to a nameserver running on a different port:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
example\.org {
|
||||
grpc \. 127\.0\.0\.1:9005
|
||||
example.org {
|
||||
grpc . 127.0.0.1:9005
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Load balance all requests between three resolvers, one of which has a IPv6 address\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
grpc \. 10\.0\.0\.10:53 10\.0\.0\.11:1053 [2003::1]:53
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Load balance all requests between three resolvers, one of which has a IPv6 address.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
grpc . 10.0.0.10:53 10.0.0.11:1053 [2003::1]:53
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Forward everything except requests to \fBexample\.org\fR
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
grpc \. 10\.0\.0\.10:1234 {
|
||||
except example\.org
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Forward everything except requests to \fB\fCexample.org\fR
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
grpc . 10.0.0.10:1234 {
|
||||
except example.org
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Proxy everything except \fBexample\.org\fR using the host\'s \fBresolv\.conf\fR\'s nameservers:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
grpc \. /etc/resolv\.conf {
|
||||
except example\.org
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Proxy everything except \fB\fCexample.org\fR using the host's \fB\fCresolv.conf\fR's nameservers:
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
grpc . /etc/resolv.conf {
|
||||
except example.org
|
||||
}
|
||||
}
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Proxy all requests to 9\.9\.9\.9 using the TLS protocol, and cache every answer for up to 30 seconds\. Note the \fBtls_servername\fR is mandatory if you want a working setup, as 9\.9\.9\.9 can\'t be used in the TLS negotiation\.
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
grpc \. 9\.9\.9\.9 {
|
||||
tls_servername dns\.quad9\.net
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Proxy all requests to 9.9.9.9 using the TLS protocol, and cache every answer for up to 30
|
||||
seconds. Note the \fB\fCtls_servername\fR is mandatory if you want a working setup, as 9.9.9.9 can't be
|
||||
used in the TLS negotiation.
|
||||
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
grpc . 9.9.9.9 {
|
||||
tls\_servername dns.quad9.net
|
||||
}
|
||||
cache 30
|
||||
}
|
||||
.
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
.RE
|
||||
|
||||
.PP
|
||||
Or with multiple upstreams from the same provider
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
|
||||
\&\. {
|
||||
grpc \. 1\.1\.1\.1 1\.0\.0\.1 {
|
||||
tls_servername cloudflare\-dns\.com
|
||||
.PP
|
||||
.RS
|
||||
|
||||
.nf
|
||||
\&. {
|
||||
grpc . 1.1.1.1 1.0.0.1 {
|
||||
tls\_servername cloudflare\-dns.com
|
||||
}
|
||||
cache 30
|
||||
}
|
||||
.
|
||||
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "BUGS"
|
||||
The TLS config is global for the whole grpc proxy if you need a different \fBtls_servername\fR for different upstreams you\'re out of luck\.
|
||||
.RE
|
||||
|
||||
.SH BUGS
|
||||
.PP
|
||||
The TLS config is global for the whole grpc proxy if you need a different \fB\fCtls_servername\fR for
|
||||
different upstreams you're out of luck.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user