README
¶
fwdpolicy
Name
fwdpolicy - is an alternate version of CoreDNS's forward plugin that adds the ability to define new forwarding policies via plugins.
Description
The fwdpolicy plugin is a copy of the forward plugin from https://github.com/coredns/coredns with an additional feature that enables you to add new policies via external plugins.
Syntax
Syntax is identical to the forward plugin from coredns/coredns. See README-forward.md, which
is a copy of the forward plugin README from coredns/coredns.
Forwarding Policy Plugins
Below is a list of forwarding policy plugins that work with this plugin. If you develop a forwarding policy plugin and think it can be useful to others, please submit a PR to add it to this list.
conditional - enables expression based forwarding policies
External Plugin
This is an external plugin. To use it, you must build CoreDNS with this plugin and any forwarding policy plugins added
to CoreDNS's plugin.cfg. The fwdpolicy plugin can either replace or be positioned adjacent the built in forward plugin.
The relative position of any forwarding policy plugin does not matter, i.e. they can be placed anywhere in the list unless
otherwise noted by the forwarding policy plugin's documentation.
Writing a Forwarding Policy Plugin
Any plugin that implements the Policy interface can be used as a forwarding policy plugin.
package fwdpolicy
type Policy interface {
List(context.Context, []*Proxy, *request.Request) []*Proxy
String() string
}
List should return an ordered list of Proxy (upstream servers) based on the desired policy behavior.
fwdpolicy, exactly as forward plugin will attempt to forward to the returned proxy servers in order received,
stopping when successful or total time elapsed exceeds timeout.
String should return the string value used when selecting the policy in the Corefile.
Examples
Forward to upstream servers 10.0.0.10, 10.0.0.11, and 10.0.0.12 using the forwarding policy defined in
the mypolicy plugin.
. {
mypolicy
fwdpolicy . 10.0.0.10 10.0.0.11 10.0.0.12 {
policy mypolicy
}
}
Notes
Originally proposed for CoreDNS's built in forward plugin https://github.com/coredns/coredns/pull/4446.
Documentation
¶
Overview ¶
Package forward implements a forwarding proxy. It caches an upstream net.Conn for some time, so if the same client returns the upstream's Conn will be precached. Depending on how you benchmark this looks to be 50% faster than just opening a new connection for every client. It works with UDP and TCP and uses inband healthchecking.
Package forward implements a forwarding proxy. It caches an upstream net.Conn for some time, so if the same client returns the upstream's Conn will be precached. Depending on how you benchmark this looks to be 50% faster than just opening a new connection for every client. It works with UDP and TCP and uses inband healthchecking.
Index ¶
- Variables
- type Forward
- func (f *Forward) ForceTCP() bool
- func (f *Forward) Len() int
- func (f *Forward) List(ctx context.Context, state *request.Request) []*Proxy
- func (f *Forward) Name() string
- func (f *Forward) OnShutdown() error
- func (f *Forward) OnStartup() (err error)
- func (f *Forward) PreferUDP() bool
- func (f *Forward) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
- func (f *Forward) SetProxy(p *Proxy)
- type HealthChecker
- type Policy
- type Proxy
- type Transport
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoHealthy means no healthy proxies left. ErrNoHealthy = errors.New("no healthy proxies") // ErrNoForward means no forwarder defined. ErrNoForward = errors.New("no forwarder defined") // ErrCachedClosed means cached connection was closed by peer. ErrCachedClosed = errors.New("cached connection was closed by peer") )
var ( RequestCount = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "requests_total", Help: "Counter of requests made per upstream.", }, []string{"to"}) RcodeCount = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "responses_total", Help: "Counter of responses received per upstream.", }, []string{"rcode", "to"}) RequestDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "request_duration_seconds", Buckets: plugin.TimeBuckets, Help: "Histogram of the time each request took.", }, []string{"to", "rcode"}) HealthcheckFailureCount = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "healthcheck_failures_total", Help: "Counter of the number of failed healthchecks.", }, []string{"to"}) HealthcheckBrokenCount = promauto.NewCounter(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "healthcheck_broken_total", Help: "Counter of the number of complete failures of the healthchecks.", }) SocketGauge = promauto.NewGaugeVec(prometheus.GaugeOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "sockets_open", Help: "Gauge of open sockets per upstream.", }, []string{"to"}) MaxConcurrentRejectCount = promauto.NewCounter(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "max_concurrent_rejects_total", Help: "Counter of the number of queries rejected because the concurrent queries were at maximum.", }) ConnCacheHitsCount = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "conn_cache_hits_total", Help: "Counter of connection cache hits per upstream and protocol.", }, []string{"to", "proto"}) ConnCacheMissesCount = promauto.NewCounterVec(prometheus.CounterOpts{ Namespace: plugin.Namespace, Subsystem: "fwdpolicy", Name: "conn_cache_misses_total", Help: "Counter of connection cache misses per upstream and protocol.", }, []string{"to", "proto"}) )
Variables declared for monitoring.
Functions ¶
This section is empty.
Types ¶
type Forward ¶
type Forward struct {
// ErrLimitExceeded indicates that a query was rejected because the number of concurrent queries has exceeded
// the maximum allowed (maxConcurrent)
ErrLimitExceeded error
Next plugin.Handler
// contains filtered or unexported fields
}
Forward represents a plugin instance that can proxy requests to another (DNS) server. It has a list of proxies each representing one upstream proxy.
func (*Forward) ForceTCP ¶
ForceTCP returns if TCP is forced to be used even when the request comes in over UDP.
func (*Forward) List ¶
List returns a set of proxies to be used for this client depending on the policy in f.
func (*Forward) OnShutdown ¶
OnShutdown stops all configured proxies.
func (*Forward) PreferUDP ¶
PreferUDP returns if UDP is preferred to be used even when the request comes in over TCP.
type HealthChecker ¶
type HealthChecker interface {
Check(*Proxy) error
SetTLSConfig(*tls.Config)
SetRecursionDesired(bool)
GetRecursionDesired() bool
}
HealthChecker checks the upstream health.
func NewHealthChecker ¶
func NewHealthChecker(trans string, recursionDesired bool) HealthChecker
NewHealthChecker returns a new HealthChecker based on transport.
type Policy ¶
type Policy interface {
List(context.Context, []*Proxy, *request.Request) []*Proxy
String() string
}
Policy defines a policy we use for selecting upstreams.
type Proxy ¶
type Proxy struct {
// contains filtered or unexported fields
}
Proxy defines an upstream host.
func (*Proxy) Healthcheck ¶
func (p *Proxy) Healthcheck()
Healthcheck kicks of a round of health checks for this proxy.
func (*Proxy) SetTLSConfig ¶
SetTLSConfig sets the TLS config in the lower p.transport and in the healthchecking client.
type Transport ¶
type Transport struct {
// contains filtered or unexported fields
}
Transport hold the persistent cache.
func (*Transport) Dial ¶
Dial dials the address configured in transport, potentially reusing a connection or creating a new one.
func (*Transport) SetTLSConfig ¶
SetTLSConfig sets the TLS config in transport.
Source Files