Skip to content

C
Coredns
Commit faf83b00 authored by Miek Gieben's avatar Miek Gieben Committed by GitHub
Browse files
Options

docs: rewrite using manpage style (#327) 

This still needs cleanup, but this is a first pass the cleans some
cruft and documents our style (in middleware.md) and makes all the
docs match that style.
parent c22b7b22
Hide whitespace changes
Inline Side-by-side
Showing with 154 additions and 128 deletions
middleware/bind/README.md
View file @ faf83b00
# bind # bind
bind overrides the host to which the server should bind. Normally, the listener binds to the *bind* overrides the host to which the server should bind. Normally, the listener binds to the
wildcard host. However, you may force the listener to bind to another IP instead. This wildcard host. However, you may force the listener to bind to another IP instead. This
directive accepts only an address, not a port. directive accepts only an address, not a port.
## Syntax ## Syntax
~~~ txt ~~~ txt
bind address bind ADDRESS
~~~ ~~~
address is the IP address to bind to. **ADDRESS** is the IP address to bind to.
## Examples ## Examples
......
middleware/cache/README.md
View file @ faf83b00
# cache # cache
`cache` enables a frontend cache. *cache* enables a frontend cache.
## Syntax ## Syntax
~~~ txt ~~~ txt
cache [ttl] [zones...] cache [TTL] [ZONES...]
~~~ ~~~
* `ttl` max TTL in seconds. If not specified, the maximum TTL will be used which is 1 hour for * **TTL** max TTL in seconds. If not specified, the maximum TTL will be used which is 1 hour for
noerror responses and half an hour for denial of existence ones. noerror responses and half an hour for denial of existence ones.
* `zones` zones it should cache for. If empty, the zones from the configuration block are used. * **ZONES** zones it should cache for. If empty, the zones from the configuration block are used.
Each element in the cache is cached according to its TTL (with `ttl` as the max). Each element in the cache is cached according to its TTL (with **TTL** as the max).
For the negative cache, the SOA's MinTTL value is used. A cache can contain up to 10,000 items by For the negative cache, the SOA's MinTTL value is used. A cache can contain up to 10,000 items by
default. default.
Or if you want more control: If you want more control:
~~~ txt ~~~ txt
cache [ttl] [zones...] { cache [TTL] [ZONES...] {
success capacity [ttl] success CAPACITY [TTL]
denial capacity [ttl] denial CAPACITY [TTL]
} }
~~~ ~~~
* `ttl` and `zones` as above. * **TTL** and **ZONES** as above.
* `success`, override the settings for caching noerror responses, capacity indicates the maximum * `success`, override the settings for caching succesful responses, **CAPACITY** indicates the maximum
number of packets we cache before we start evicting (LRU). Ttl overrides the cache maximum TTL. number of packets we cache before we start evicting (LRU). **TTL** overrides the cache maximum TTL.
* `denial`, override the settings for caching denial of existence responses, capacity indicates the maximum * `denial`, override the settings for caching denial of existence responses, **CAPACITY** indicates the maximum
number of packets we cache before we start evicting (LRU). Ttl overrides the cache maximum TTL. number of packets we cache before we start evicting (LRU). **TTL** overrides the cache maximum TTL.
There is a third category (`error`) but those responses are never cached. There is a third category (`error`) but those responses are never cached.
The minimum TTL allowed on resource records is 5 seconds. The minimum TTL allowed on resource records is 5 seconds.
If monitoring is enabled (via the `prometheus` directive) then the following extra metrics are added: If monitoring is enabled (via the *prometheus* directive) then the following extra metrics are added:
* coredns_cache_hit_count_total, and * coredns_cache_hit_count_total, and
* coredns_cache_miss_count_total * coredns_cache_miss_count_total
......
middleware/chaos/README.md
View file @ faf83b00
# chaos # chaos
The `chaos` middleware allows CoreDNS to respond to TXT queries in the CH class. The *chaos* middleware allows CoreDNS to respond to TXT queries in the CH class.
This is useful for retrieving version or author information from the server. This is useful for retrieving version or author information from the server.
## Syntax ## Syntax
~~~ ~~~
chaos [version] [authors...] chaos [VERSION] [AUTHORS...]
~~~ ~~~
* `version` the version to return. Defaults to CoreDNS-<version>, if not set. * **VERSION** the version to return. Defaults to CoreDNS-<version>, if not set.
* `authors` what authors to return. No default. * **AUTHORS** what authors to return. No default.
Note that you have to make sure that this middleware will get actual queries for the Note that you have to make sure that this middleware will get actual queries for the
following zones: `version.bind`, `version.server`, `authors.bind`, `hostname.bind` and following zones: `version.bind`, `version.server`, `authors.bind`, `hostname.bind` and
......
middleware/dnssec/README.md
View file @ faf83b00
# dnssec # dnssec
`dnssec` enables on-the-fly DNSSEC signing of served data. *dnssec* enables on-the-fly DNSSEC signing of served data.
## Syntax ## Syntax
~~~ ~~~
dnssec [zones...] dnssec [ZONES...]
~~~ ~~~
* `zones` zones that should be signed. If empty, the zones from the configuration block * **ZONES** zones that should be signed. If empty, the zones from the configuration block
are used. are used.
If keys are not specified (see below), a key is generated and used for all signing operations. The If keys are not specified (see below), a key is generated and used for all signing operations. The
...@@ -23,10 +23,9 @@ NOTE: Key generation has not been implemented yet. ...@@ -23,10 +23,9 @@ NOTE: Key generation has not been implemented yet.
TODO(miek): think about key rollovers, and how to do them automatically. TODO(miek): think about key rollovers, and how to do them automatically.
~~~ ~~~
dnssec [zones... ] { dnssec [ZONES... ] {
key file [key...] key file KEY...
} }
~~~ ~~~
......
middleware/errors/README.md
View file @ faf83b00
# errors # errors
`errors` allows you to set custom error pages and enable error logging. *errors* enables error logging.
By default, error responses (HTTP status >= 400) are not logged and the client receives a plaintext error message. TODO: what are errors.
Using an error log, the text of each error will be recorded so you can determine what is going wrong without exposing those details to the clients. With error pages, you can present custom error messages and instruct your visitor with what to do.
## Syntax ## Syntax
~~~ ~~~
errors [logfile] errors [LOGFILE]
~~~ ~~~
* `logfile` is the path to the error log file to create (or append to), relative to the current working directory. It can also be stdout or stderr to write to the console, syslog to write to the system log (except on Windows), or visible to write the error (including full stack trace, if applicable) to the response. Writing errors to the response is NOT advised except in local debug situations. The default is stderr. * **LOGFILE** is the path to the error log file to create (or append to), relative to the current
The above syntax will simply enable error reporting on the server. To specify custom error pages, open a block: working directory. It can also be `stdout` or `stderr` to write to the console, syslog to write to the
system log (except on Windows), or visible to write the error (including full stack trace, if
applicable) to the response. Writing errors to the response is NOT advised except in local debug
situations. The default is stderr. The above syntax will simply enable error reporting on the
server. To specify custom error pages, open a block:
TODO(miek): check what is actually implemented and clean this up!
~~~ ~~~
errors { errors {
......
middleware/etcd/README.md
View file @ faf83b00
# etcd # etcd
`etcd` enables reading zone data from an etcd instance. The data in etcd has to be encoded as *etcd* enables reading zone data from an etcd instance. The data in etcd has to be encoded as
a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26) a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26)
like [SkyDNS](https//github.com/skynetservices/skydns). It should also work just like SkyDNS. like [SkyDNS](https//github.com/skynetservices/skydns). It should also work just like SkyDNS.
...@@ -10,10 +10,10 @@ in the network. ...@@ -10,10 +10,10 @@ in the network.
## Syntax ## Syntax
~~~ ~~~
etcd [zones...] etcd [ZONES...]
~~~ ~~~
* `zones` zones etcd should be authoritative for. * **ZONES** zones etcd should be authoritative for.
The path will default to `/skydns` the local etcd proxy (http://localhost:2379). The path will default to `/skydns` the local etcd proxy (http://localhost:2379).
If no zones are specified the block's zone will be used as the zone. If no zones are specified the block's zone will be used as the zone.
...@@ -21,20 +21,20 @@ If no zones are specified the block's zone will be used as the zone. ...@@ -21,20 +21,20 @@ If no zones are specified the block's zone will be used as the zone.
If you want to `round robin` A and AAAA responses look at the `loadbalance` middleware. If you want to `round robin` A and AAAA responses look at the `loadbalance` middleware.
~~~ ~~~
etcd [zones...] { etcd [ZONES...] {
stubzones stubzones
path /skydns path PATH
endpoint endpoint... endpoint ENDPOINT...
upstream address... upstream ADDRESS...
tls cert key cacert tls CERT KEY CACERt
debug debug
} }
~~~ ~~~
* `stubzones` enables the stub zones feature. The stubzone is *only* done in the etcd tree located * `stubzones` enables the stub zones feature. The stubzone is *only* done in the etcd tree located
under the *first* zone specified. under the *first* zone specified.
* `path` the path inside etcd. Defaults to "/skydns". * **PATH** the path inside etcd. Defaults to "/skydns".
* `endpoint` the etcd endpoints. Defaults to "http://localhost:2397". * **ENDPOINT** the etcd endpoints. Defaults to "http://localhost:2397".
* `upstream` upstream resolvers to be used resolve external names found in etcd (think CNAMEs) * `upstream` upstream resolvers to be used resolve external names found in etcd (think CNAMEs)
pointing to external names. If you want CoreDNS to act as a proxy for clients, you'll need to add pointing to external names. If you want CoreDNS to act as a proxy for clients, you'll need to add
the proxy middleware. the proxy middleware.
...@@ -129,4 +129,3 @@ Any errors seen doing parsing will show up like this: ...@@ -129,4 +129,3 @@ Any errors seen doing parsing will show up like this:
. 0 CH TXT "/skydns/local/skydns/r/a: invalid character '.' after object key:value pair" . 0 CH TXT "/skydns/local/skydns/r/a: invalid character '.' after object key:value pair"
which shows `a.r.skydns.local.` has a json encoding problem. which shows `a.r.skydns.local.` has a json encoding problem.
middleware/file/README.md
View file @ faf83b00
# file # file
`file` enables serving zone data from an RFC 1035-style master file. *file* enables serving zone data from an RFC 1035-style master file.
The file middleware is used for an "old-style" DNS server. It serves from a preloaded file that exists The file middleware is used for an "old-style" DNS server. It serves from a preloaded file that exists
on disk. If the zone file contains signatures (i.e. is signed, i.e. DNSSEC) correct DNSSEC answers on disk. If the zone file contains signatures (i.e. is signed, i.e. DNSSEC) correct DNSSEC answers
...@@ -10,27 +10,27 @@ zonefile. ...@@ -10,27 +10,27 @@ zonefile.
## Syntax ## Syntax
~~~ ~~~
file dbfile [zones...] file DBFILE [ZONES...]
~~~ ~~~
* `dbfile` the database file to read and parse. * **DBFILE** the database file to read and parse.
* `zones` zones it should be authoritative for. If empty, the zones from the configuration block * **ZONES** zones it should be authoritative for. If empty, the zones from the configuration block
are used. are used.
If you want to round robin A and AAAA responses look at the `loadbalance` middleware. If you want to round robin A and AAAA responses look at the *loadbalance* middleware.
TSIG key configuration is TODO; directive format for transfer will probably be extended with TSIG key configuration is TODO; directive format for transfer will probably be extended with
TSIG key information, something like `transfer out [address...] key [name] [base64]` TSIG key information, something like `transfer out [ADDRESS...] key [NAME[:ALG]] [BASE64]`
~~~ ~~~
file dbfile [zones... ] { file DBFILE [ZONES... ] {
transfer to [address...] transfer to ADDRESS...
no_reload no_reload
} }
~~~ ~~~
* `transfer` enables zone transfers. It may be specified multiples times. *To* or *from* signals * `transfer` enables zone transfers. It may be specified multiples times. `To` or `from` signals
the direction. Addresses must be denoted in CIDR notation (127.0.0.1/32 etc.) or just as plain the direction. **ADDRESS** must be denoted in CIDR notation (127.0.0.1/32 etc.) or just as plain
addresses. The special wildcard `*` means: the entire internet (only valid for 'transfer to'). addresses. The special wildcard `*` means: the entire internet (only valid for 'transfer to').
When an address is specified a notify message will be send whenever the zone is reloaded. When an address is specified a notify message will be send whenever the zone is reloaded.
* `no_reload` by default CoreDNS will reload a zone from disk whenever it detects a change to the * `no_reload` by default CoreDNS will reload a zone from disk whenever it detects a change to the
......
middleware/health/README.md
View file @ faf83b00
# health # health
This module enables a simple health check. This module enables a simple health check endpoint.
By default it will listen on port 8080. By default it will listen on port 8080.
Restarting CoreDNS will stop the health checking. This is a bug. Also [this upstream
Caddy bug](https://github.com/mholt/caddy/issues/675).
## Syntax ## Syntax
~~~ ~~~
health health [ADDRESS]
~~~ ~~~
Optionally takes an address; the default is `:8080`. The health path is fixed to `/health`. It Optionally takes an address; the default is `:8080`. The health path is fixed to `/health`. It
will just return "OK" when CoreDNS is healthy. will just return "OK" when CoreDNS is healthy, which currently mean: it is up and running.
This middleware only needs to be enabled once. This middleware only needs to be enabled once.
......
middleware/kubernetes/README.md
View file @ faf83b00
# kubernetes # kubernetes
`kubernetes` enables reading zone data from a kubernetes cluster. Record names *kubernetes* enables reading zone data from a kubernetes cluster. Record names
are constructed as "myservice.mynamespace.coredns.local" where: are constructed as "myservice.mynamespace.coredns.local" where:
* "myservice" is the name of the k8s service (this may include multiple DNS labels, * "myservice" is the name of the k8s service (this may include multiple DNS labels,
...@@ -13,19 +13,23 @@ The record name format can be changed by specifying a name template in the Coref ...@@ -13,19 +13,23 @@ The record name format can be changed by specifying a name template in the Coref
## Syntax ## Syntax
~~~ ~~~
kubernetes [zones...] kubernetes [ZONES...]
~~~ ~~~
* `zones` zones kubernetes should be authorative for. Overlapping zones are ignored. * `ZONES` zones kubernetes should be authorative for. Overlapping zones are ignored.
Or if you want to specify an endpoint:
~~~ ~~~
kubernetes [zones] { kubernetes [ZONES...] {
endpoint http://localhost:8080 endpoint ENDPOINT
} }
~~~ ~~~
* `endpoint` the kubernetes API endpoint, default to http://localhost:8080 * **ENDPOINT** the kubernetes API endpoint, defaults to http://localhost:8080
TODO(...): Add all the other options.
## Examples ## Examples
...@@ -41,8 +45,8 @@ This is the default kubernetes setup, with everything specified in full: ...@@ -41,8 +45,8 @@ This is the default kubernetes setup, with everything specified in full:
resyncperiod 5m resyncperiod 5m
# Use url for k8s API endpoint # Use url for k8s API endpoint
endpoint https://k8sendpoint:8080 endpoint https://k8sendpoint:8080
# The tls cert, key and the CA cert filenames # The tls cert, key and the CA cert filenames
tls cert key cacert tls cert key cacert
# Assemble k8s record names with the template # Assemble k8s record names with the template
template {service}.{namespace}.{zone} template {service}.{namespace}.{zone}
# Only expose the k8s namespace "demo" # Only expose the k8s namespace "demo"
...@@ -69,8 +73,9 @@ Defaults: ...@@ -69,8 +73,9 @@ Defaults:
is required. The label selector syntax is described in the kubernetes API documentation at: is required. The label selector syntax is described in the kubernetes API documentation at:
http://kubernetes.io/docs/user-guide/labels/ http://kubernetes.io/docs/user-guide/labels/
### Template syntax ### Template Syntax
Record name templates can be constructed using the symbolic elements: Record name templates can be constructed using the symbolic elements:
| template symbol | description | | template symbol | description |
| `{service}` | Kubernetes object/service name. | | `{service}` | Kubernetes object/service name. |
| `{namespace}` | The kubernetes namespace. | | `{namespace}` | The kubernetes namespace. |
...@@ -81,10 +86,9 @@ Record name templates can be constructed using the symbolic elements: ...@@ -81,10 +86,9 @@ Record name templates can be constructed using the symbolic elements:
#### Launch Kubernetes #### Launch Kubernetes
Kubernetes is launched using the commands in the `contrib/kubernetes/testscripts/00_run_k8s.sh` script. Kubernetes is launched using the commands in the `.travis/kubernetes/00_run_k8s.sh` script.
#### Configure kubectl and Test
#### Configure kubectl and test
The kubernetes control client can be downloaded from the generic URL: The kubernetes control client can be downloaded from the generic URL:
`http://storage.googleapis.com/kubernetes-release/release/${K8S_VERSION}/bin/${GOOS}/${GOARCH}/${K8S_BINARY}` `http://storage.googleapis.com/kubernetes-release/release/${K8S_VERSION}/bin/${GOOS}/${GOARCH}/${K8S_BINARY}`
...@@ -95,7 +99,6 @@ For example, the kubectl client for Linux can be downloaded using the command: ...@@ -95,7 +99,6 @@ For example, the kubectl client for Linux can be downloaded using the command:
The `contrib/kubernetes/testscripts/10_setup_kubectl.sh` script can be stored in the same directory as The `contrib/kubernetes/testscripts/10_setup_kubectl.sh` script can be stored in the same directory as
kubectl to setup kubectl to communicate with kubernetes running on the localhost. kubectl to setup kubectl to communicate with kubernetes running on the localhost.
#### Launch a kubernetes service and expose the service #### Launch a kubernetes service and expose the service
The following commands will create a kubernetes namespace "demo", The following commands will create a kubernetes namespace "demo",
...@@ -112,7 +115,7 @@ $ ./kubectl expose deployment mynginx --namespace=demo --port=80 ...@@ -112,7 +115,7 @@ $ ./kubectl expose deployment mynginx --namespace=demo --port=80
$ ./kubectl get service --namespace=demo $ ./kubectl get service --namespace=demo
~~~ ~~~
The script `contrib/kubernetes/testscripts/20_setup_k8s_services.sh` creates a couple of sample namespaces The script `.travis/kubernetes/20_setup_k8s_services.sh` creates a couple of sample namespaces
with services running in those namespaces. The automated kubernetes integration tests in with services running in those namespaces. The automated kubernetes integration tests in
`test/kubernetes_test.go` depend on these services and namespaces to exist in kubernetes. `test/kubernetes_test.go` depend on these services and namespaces to exist in kubernetes.
...@@ -125,7 +128,7 @@ Build CoreDNS and launch using this configuration file: ...@@ -125,7 +128,7 @@ Build CoreDNS and launch using this configuration file:
# Serve on port 53 # Serve on port 53
.:53 { .:53 {
kubernetes coredns.local { kubernetes coredns.local {
resyncperiod 5m resyncperiod 5m
endpoint http://localhost:8080 endpoint http://localhost:8080
template {service}.{namespace}.{zone} template {service}.{namespace}.{zone}
namespaces demo namespaces demo
...@@ -154,10 +157,6 @@ In a separate terminal a DNS query can be issued using dig: ...@@ -154,10 +157,6 @@ In a separate terminal a DNS query can be issued using dig:
~~~ ~~~
$ dig @localhost mynginx.demo.coredns.local $ dig @localhost mynginx.demo.coredns.local
; <<>> DiG 9.9.4-RedHat-9.9.4-29.el7_2.3 <<>> @localhost mynginx.demo.coredns.local
; (2 servers found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 47614 ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 47614
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1 ;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
...@@ -176,6 +175,7 @@ mynginx.demo.coredns.local. 0 IN A 10.0.0.10 ...@@ -176,6 +175,7 @@ mynginx.demo.coredns.local. 0 IN A 10.0.0.10
~~~ ~~~
TODO(miek|...): below this line file bugs or issues and cleanup:
## Implementation Notes/Ideas ## Implementation Notes/Ideas
......
middleware/loadbalance/README.md
View file @ faf83b00
# loadbalance # loadbalance
`loadbalance` acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records in the answer. See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and cons *loadbalance* acts as a round-robin DNS loadbalancer by randomizing the order of A and AAAA records
on this setup. in the answer. See [Wikipedia](https://en.wikipedia.org/wiki/Round-robin_DNS) about the pros and
cons on this setup.
It will take care to sort any CNAMEs before any address records, because some stub resolver It will take care to sort any CNAMEs before any address records, because some stub resolver
implementations (like glibc) are particular about that. implementations (like glibc) are particular about that.
...@@ -9,10 +10,10 @@ implementations (like glibc) are particular about that. ...@@ -9,10 +10,10 @@ implementations (like glibc) are particular about that.
## Syntax ## Syntax
~~~ ~~~
loadbalance [policy] loadbalance [POLICY]
~~~ ~~~
* `policy` is how to balance, the default is "round_robin" * **POLICY** is how to balance, the default is "round_robin"
## Examples ## Examples
......
middleware/log/README.md
View file @ faf83b00
# log # log
`log` enables query logging. *log* enables query logging.
## Syntax ## Syntax
...@@ -9,31 +9,30 @@ log ...@@ -9,31 +9,30 @@ log
~~~ ~~~
* With no arguments, a query log entry is written to query.log in the common log format for all requests * With no arguments, a query log entry is written to query.log in the common log format for all requests
(base name = .).
~~~ txt ~~~ txt
log file log FILE
~~~ ~~~
* file is the log file to create (or append to). The base name is assumed to be '.' . * **FILE** is the log file to create (or append to).
~~~ txt ~~~ txt
log [name] [file] [format] log [NAME] FILE [FORMAT]
~~~ ~~~
* `name` is the base name to match in order to be logged * `NAME` is the name to match in order to be logged
* `file` is the log file to create (or append to) * `FILE` is the log file to create (or append to)
* `format` is the log format to use (default is Common Log Format) * `FORMAT` is the log format to use (default is Common Log Format)
You can further specify the class of responses that get logged: You can further specify the class of responses that get logged:
~~~ txt ~~~ txt
log [name] [file] [format] { log [NAME] FILE [FORMAT] {
class [success|denial|error|all] class [success|denial|error|all]
} }
~~~ ~~~
Here *success*, *denial* and *error* denotes the class of responses that should be logged. The Here `success` `denial` and `error` denotes the class of responses that should be logged. The
classes have the following meaning: classes have the following meaning:
* `success`: successful response * `success`: successful response
......
middleware/metrics/README.md
View file @ faf83b00
...@@ -35,7 +35,7 @@ Caddy bug](https://github.com/mholt/caddy/issues/675). ...@@ -35,7 +35,7 @@ Caddy bug](https://github.com/mholt/caddy/issues/675).
## Syntax ## Syntax
~~~ ~~~
prometheus prometheus [ADDRESS]
~~~ ~~~
For each zone that you want to see metrics for. For each zone that you want to see metrics for.
......
middleware/middleware.md 0 → 100644
View file @ faf83b00
# Middleware
# Documentation
Each middleware should have a README.md explaining what the middleware does and how it is
configured. The file should have the following layout:
* Title: use the middleware's name
* Subsection titled: "Syntax"
* Subsection titled: "Examples"
More sections are of course possible.
## Style
We use the Unix manual page style:
* The name of middleware in the running text should be italic: *middleware*.
* all CAPITAL: user supplied argument, in the running text references this use strong text: `**`:
**EXAMPLE**.
* Optional text: in block quotes: `[optional]`.
* Use three dots to indicate multiple options are allowed: `arg...`.
* Item used literal: `literal`.
middleware/pprof/README.md
View file @ faf83b00
# pprof # pprof
pprof publishes runtime profiling data at endpoints under /debug/pprof. You can visit /debug/pprof *pprof* publishes runtime profiling data at endpoints under /debug/pprof. You can visit
`/debug/pprof`
on your site for an index of the available endpoints. By default it will listen on localhost:6053. on your site for an index of the available endpoints. By default it will listen on localhost:6053.
> This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If > This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If
...@@ -10,6 +11,8 @@ For more information, please see [Go's pprof ...@@ -10,6 +11,8 @@ For more information, please see [Go's pprof
documentation](https://golang.org/pkg/net/http/pprof/s://golang.org/pkg/net/http/pprof/) and read documentation](https://golang.org/pkg/net/http/pprof/s://golang.org/pkg/net/http/pprof/) and read
[Profiling Go Programs](https://blog.golang.org/profiling-go-programs). [Profiling Go Programs](https://blog.golang.org/profiling-go-programs).
There is not configuration.
## Syntax ## Syntax
~~~ ~~~
......
middleware/proxy/README.md
View file @ faf83b00
# proxy # proxy
`proxy` facilitates both a basic reverse proxy and a robust load balancer. The proxy has support for *proxy* facilitates both a basic reverse proxy and a robust load balancer. The proxy has support for
multiple backends and adding custom headers. The load balancing features include multiple policies, multiple backends. The load balancing features include multiple policies, health checks, and
health checks, and failovers. If all hosts fail their health check the proxy middleware will fail failovers. If all hosts fail their health check the proxy middleware will fail back to randomly
back to randomly selecting a target and sending packets to it. selecting a target and sending packets to it.
## Syntax ## Syntax
In its most basic form, a simple reverse proxy uses this syntax: In its most basic form, a simple reverse proxy uses this syntax:
~~~ ~~~
proxy from to proxy FROM To
~~~ ~~~
* `from` is the base path to match for the request to be proxied * **FROM** is the base path to match for the request to be proxied
* `to` is the destination endpoint to proxy to * **TO** is the destination endpoint to proxy to
However, advanced features including load balancing can be utilized with an expanded syntax: However, advanced features including load balancing can be utilized with an expanded syntax:
~~~ ~~~
proxy from to... { proxy FROM TO... {
policy random | least_conn | round_robin policy random|least_conn|round_robin
fail_timeout duration fail_timeout DURATION
max_fails integer max_fails INTEGER
health_check path:port [duration] health_check PATH:PORT [DURATION]
except ignored_names... except IGNORED_NAMES...
spray spray
} }
~~~ ~~~
* `from` is the base path to match for the request to be proxied. * **FROM** is the name to match for the request to be proxied.
* `to` is the destination endpoint to proxy to. At least one is required, but multiple may be specified. * **TO** is the destination endpoint to proxy to. At least one is required, but multiple may be specified.
* `policy` is the load balancing policy to use; applies only with multiple backends. May be one of random, least_conn, or round_robin. Default is random. * `policy` is the load balancing policy to use; applies only with multiple backends. May be one of random, least_conn, or round_robin. Default is random.
* `fail_timeout` specifies how long to consider a backend as down after it has failed. While it is down, requests will not be routed to that backend. A backend is "down" if CoreDNS fails to communicate with it. The default value is 10 seconds ("10s"). * `fail_timeout` specifies how long to consider a backend as down after it has failed. While it is down, requests will not be routed to that backend. A backend is "down" if CoreDNS fails to communicate with it. The default value is 10 seconds ("10s").
* `max_fails` is the number of failures within fail_timeout that are needed before considering a backend to be down. If 0, the backend will never be marked as down. Default is 1. * `max_fails` is the number of failures within fail_timeout that are needed before considering a backend to be down. If 0, the backend will never be marked as down. Default is 1.
...@@ -41,9 +41,9 @@ proxy from to... { ...@@ -41,9 +41,9 @@ proxy from to... {
## Policies ## Policies
There are three load-balancing policies available: There are three load-balancing policies available:
* *random* (default) - Randomly select a backend * `random` (default) - Randomly select a backend
* *least_conn* - Select the backend with the fewest active connections * `least_conn` - Select the backend with the fewest active connections
* *round_robin* - Select the backend in round-robin fashion * `round_robin` - Select the backend in round-robin fashion
All polices implement randomly spraying packets to backend hosts when *no healthy* hosts are All polices implement randomly spraying packets to backend hosts when *no healthy* hosts are
available. This is to preeempt the case where the healthchecking (as a mechanism) fails. available. This is to preeempt the case where the healthchecking (as a mechanism) fails.
......
middleware/rewrite/README.md
View file @ faf83b00
# rewrite # rewrite
`rewrite` performs internal message rewriting. Rewrites are invisible to the client. *rewrite* performs internal message rewriting. Rewrites are invisible to the client.
There are simple rewrites (fast) and complex rewrites (slower), but they're powerful enough to There are simple rewrites (fast) and complex rewrites (slower), but they're powerful enough to
accommodate most dynamic back-end applications. accommodate most dynamic back-end applications.
## Syntax ## Syntax
~~~ ~~~
rewrite from to rewrite FROM TO
~~~ ~~~
* from is the exact name of type to match * **FROM** is the exact name of type to match
* to is the destination name or type to rewrite to * **TO** is the destination name or type to rewrite to
If from *and* to look like a DNS type (`A`, `MX`, etc.), the type of the message will be rewriten; If from *and* to look like a DNS type (`A`, `MX`, etc.), the type of the message will be rewriten;
e.g., to rewrite ANY queries to HINFO, use `rewrite ANY HINFO`. e.g., to rewrite ANY queries to HINFO, use `rewrite ANY HINFO`.
......
middleware/secondary/README.md
View file @ faf83b00
# secondary # secondary
`secondary` enables serving a zone retrieved from a primary server. *secondary* enables serving a zone retrieved from a primary server.
## Syntax ## Syntax
~~~ ~~~
secondary [zones...] secondary [ZONES...]
~~~ ~~~
* `zones` zones it should be authoritative for. If empty, the zones from the configuration block * **ZONES** zones it should be authoritative for. If empty, the zones from the configuration block
are used. Note that without a remote address to *get* the zone from, the above is not that useful. are used. Note that without a remote address to *get* the zone from, the above is not that useful.
A working syntax would be: A working syntax would be:
~~~ ~~~
secondary [zones...] { secondary [zones...] {
transfer from address transfer from ADDRESS
[transfer to address] [transfer to ADDRESS]
} }
~~~ ~~~
...@@ -27,7 +27,7 @@ secondary [zones...] { ...@@ -27,7 +27,7 @@ secondary [zones...] {
## Examples ## Examples
~~~ ~~~
secondary [zones...] { secondary example.org {
transfer from 10.0.1.1 transfer from 10.0.1.1
transfer from 10.1.2.1 transfer from 10.1.2.1
} }
......
middleware/whoami/README.md
View file @ faf83b00
# whoami # whoami
whoami returns your local IP address, port and transport used. Your local IP address is returned in *whoami* returns your local IP address, port and transport used. Your local IP address is returned in
the additional section as either an A or AAAA record. the additional section as either an A or AAAA record.
The port and transport are included in the additional section as a SRV record, transport can be The port and transport are included in the additional section as a SRV record, transport can be
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment