.\" 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"
In its most basic form:
.
.IP "" 4
.
.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
Extra knobs are available with an expanded syntax:
.
.IP "" 4
.
.nf

grpc FROM TO\.\.\. {
    except IGNORED_NAMES\.\.\.
    tls CERT KEY CA
    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

.
.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
}
.
.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
.
.IP "" 0
.
.P
Forward everything except requests to \fBexample\.org\fR
.
.IP "" 4
.
.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
.
.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
    }
    cache 30
}
.
.fi
.
.IP "" 0
.
.P
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
    }
    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\.