README: add DoH example (#3096)

Show example for DoH. And cleanup the README (format to 80 column
linewidth).

Fixes: #3094

Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben
2019-08-08 15:17:53 +01:00
committed by GitHub
parent 883d47685f
commit 935354deb3

View File

@@ -29,15 +29,17 @@ Currently CoreDNS is able to:
* Allow for zone transfers, i.e., act as a primary server (*file*).
* Automatically load zone files from disk (*auto*).
* Caching of DNS responses (*cache*).
* Use etcd as a backend (replace [SkyDNS](https://github.com/skynetservices/skydns)) (*etcd*).
* Use etcd as a backend (replacing [SkyDNS](https://github.com/skynetservices/skydns)) (*etcd*).
* Use k8s (kubernetes) as a backend (*kubernetes*).
* Serve as a proxy to forward queries to some other (recursive) nameserver (*forward*).
* Provide metrics (by using Prometheus) (*metrics*).
* Provide query (*log*) and error (*errors*) logging.
* Integrate with cloud providers (*route53*).
* Support the CH class: `version.bind` and friends (*chaos*).
* Support the RFC 5001 DNS name server identifier (NSID) option (*nsid*).
* Profiling support (*pprof*).
* Rewrite queries (qtype, qclass and qname) (*rewrite* and *template*).
* Block ANY queries (*any*).
And more. Each of the plugins is documented. See [coredns.io/plugins](https://coredns.io/plugins)
for all in-tree plugins, and [coredns.io/explugins](https://coredns.io/explugins) for all
@@ -45,11 +47,13 @@ out-of-tree plugins.
## Compilation from Source
To compile CoreDNS, we assume you have a working Go setup. See various tutorials if you dont have that already configured.
To compile CoreDNS, we assume you have a working Go setup. See various tutorials if you dont have
that already configured.
First, make sure your golang version is 1.12 or higher as `go mod` support is needed.
See [here](https://github.com/golang/go/wiki/Modules) for `go mod` details.
Then, check out the project and run `make` to compile the binary:
~~~
$ git clone https://github.com/coredns/coredns
$ cd coredns
@@ -60,8 +64,8 @@ This should yield a `coredns` binary.
## Compilation with Docker
CoreDNS requires Go to compile. However, if you already have docker installed and prefer not to setup
a Go environment, you could build CoreDNS easily:
CoreDNS requires Go to compile. However, if you already have docker installed and prefer not to
setup a Go environment, you could build CoreDNS easily:
```
$ docker run --rm -i -t -v $PWD:/go/src/github.com/coredns/coredns \
@@ -85,8 +89,8 @@ CoreDNS-001
Any query sent to port 53 should return some information; your sending address, port and protocol
used.
If you have a Corefile without a port number specified it will, by default, use port 53, but you
can override the port with the `-dns.port` flag:
If you have a Corefile without a port number specified it will, by default, use port 53, but you can
override the port with the `-dns.port` flag:
`./coredns -dns.port 1053`, runs the server on port 1053.
@@ -101,8 +105,8 @@ Start a simple proxy. You'll need to be root to start listening on port 53.
}
~~~
Just start CoreDNS: `./coredns`. Then just query on that port (53). The query should be forwarded to
8.8.8.8 and the response will be returned. Each query should also show up in the log which is
Just start CoreDNS: `./coredns`. Then just query on that port (53). The query should be forwarded
to 8.8.8.8 and the response will be returned. Each query should also show up in the log which is
printed on standard output.
Serve the (NSEC) DNSSEC-signed `example.org` on port 1053, with errors and logging sent to standard
@@ -120,8 +124,8 @@ example.org:1053 {
}
~~~
Serve `example.org` on port 1053, but forward everything that does *not* match `example.org` to a recursive
nameserver *and* rewrite ANY queries to HINFO.
Serve `example.org` on port 1053, but forward everything that does *not* match `example.org` to a
recursive nameserver *and* rewrite ANY queries to HINFO.
~~~ txt
.:1053 {
@@ -152,7 +156,7 @@ add the closing dot: `10.0.0.0/24.` as this also stops the conversion.
This even works for CIDR (See RFC 1518 and 1519) addressing, i.e. `10.0.0.0/25`, CoreDNS will then
check if the `in-addr` request falls in the correct range.
Listening on TLS and for gRPC? Use:
Listening on TLS (DoT) and for gRPC? Use:
~~~ corefile
tls://example.org grpc://example.org {
@@ -160,6 +164,14 @@ tls://example.org grpc://example.org {
}
~~~
And for DNS over HTTP/2 (DoH) use:
~~~ corefile
https://example.org {
whoami
}
~~~
Specifying ports works in the same way:
~~~ txt
@@ -186,7 +198,8 @@ More resources can be found:
## Contribution guidelines
If you want to contribute to CoreDNS, be sure to review the [contribution guidelines](CONTRIBUTING.md).
If you want to contribute to CoreDNS, be sure to review the [contribution
guidelines](CONTRIBUTING.md).
## Deployment
@@ -210,8 +223,8 @@ And finally 1.4.1 that removes the config workarounds.
## Security
### Security Audit
A third party security audit was performed by Cure53, you can see the full report [here](https://coredns.io/assets/DNS-01-report.pdf).
A third party security audit was performed by Cure53, you can see the full report
[here](https://coredns.io/assets/DNS-01-report.pdf).
### Reporting security vulnerabilities
@@ -219,4 +232,5 @@ If you find a security vulnerability or any security related issues, please DO N
issue, instead send your report privately to `security@coredns.io`. Security reports are greatly
appreciated and we will publicly thank you for it.
Please consult [security vulnerability disclosures and security fix and release process document](https://github.com/coredns/coredns/blob/master/SECURITY-RELEASE-PROCESS.md)
Please consult [security vulnerability disclosures and security fix and release process
document](https://github.com/coredns/coredns/blob/master/SECURITY-RELEASE-PROCESS.md)