dnsproxy

Documentation

Index

• Constants
• func ExtractMsgDetails(msg *dns.Msg) (qname string, responseIPs []net.IP, TTL uint32, CNAMEs []string, rcode int, ...)
• type DNSProxy
  • func StartDNSProxy(address string, port uint16, lookupEPFunc LookupEndpointIDByIPFunc, ...) (*DNSProxy, error)
  • func (p *DNSProxy) AddAllowed(reStr, endpointID string)
  • func (p *DNSProxy) CheckAllowed(name, endpointID string) bool
  • func (p *DNSProxy) RemoveAllowed(reStr, endpointID string)
  • func (p *DNSProxy) ServeDNS(w dns.ResponseWriter, request *dns.Msg)
  • func (p *DNSProxy) SetRejectReply(opt string)
  • func (p *DNSProxy) UpdateAllowed(reStrToAdd, reStrToRemove []string, endpointID string)
• type LookupEndpointIDByIPFunc
• type NotifyOnDNSMsgFunc
• type ProxyRequestContext
  • func (proxyStat *ProxyRequestContext) IsTimeout() bool

Constants

const (
	// ProxyForwardTimeout is the maximum time to wait for DNS responses to
	// forwarded DNS requests. This is needed since UDP queries have no way to
	// indicate that the client has stopped expecting a response.
	ProxyForwardTimeout = 10 * time.Second

	// ProxyBindTimeout is how long we wait for a successful bind to the bindaddr.
	// Note: This must be divisible by 5 without going to 0
	ProxyBindTimeout = 20 * time.Second

	// ProxyBindRetryInterval is how long to wait between attempts to bind to the
	// proxy address:port
	ProxyBindRetryInterval = ProxyBindTimeout / 5
)

Functions

func ExtractMsgDetails

func ExtractMsgDetails(msg *dns.Msg) (qname string, responseIPs []net.IP, TTL uint32, CNAMEs []string, rcode int, answerTypes []uint16, qTypes []uint16, err error)

ExtractMsgDetails extracts a canonical query name, any IPs in a response, the lowest applicable TTL, rcode, anwer rr types and question types When a CNAME is returned the chain is collapsed down, keeping the lowest TTL, and CNAME targets are returned.

Types

type DNSProxy

type DNSProxy struct {
	// BindAddr is the local address the server is using to listen for DNS
	// requests. This is a read-only value and reflects the actual value. Passing
	// ":0" to StartDNSProxy will allow the kernel to set the port, and that can
	// be read here.
	BindAddr string

	// BindPort is the port in BindAddr.
	BindPort uint16

	// LookupendpointIDByIP is a provided callback that returns the endpoint ID
	// as a string.
	// Note: this is a little pointless since this proxy is in-process but it is
	// intended to allow us to switch to an external proxy process by forcing the
	// design now.
	LookupEndpointIDByIP LookupEndpointIDByIPFunc

	// NotifyOnDNSMsg is a provided callback by which the proxy can emit DNS
	// response data. It is intended to wire into a DNS cache and a
	// fqdn.NameManager.
	// Note: this is a little pointless since this proxy is in-process but it is
	// intended to allow us to switch to an external proxy process by forcing the
	// design now.
	NotifyOnDNSMsg NotifyOnDNSMsgFunc

	// UDPServer, TCPServer are the miekg/dns server instances. They handle DNS
	// parsing etc. for us.
	UDPServer, TCPServer *dns.Server

	// UDPClient, TCPClient are the miekg/dns client instances. Forwarded
	// requests are made with these clients but are sent to the originally
	// intended DNS server.
	// Note: The DNS request ID is randomized but when seeing a lot of traffic we
	// may still exhaust the 16-bit ID space for our (source IP, source Port) and
	// this may cause DNS disruption. A client pool may be better.
	UDPClient, TCPClient *dns.Client

	// this mutex protects variables below this point
	lock.Mutex
	// contains filtered or unexported fields
}

DNSProxy is a L7 proxy for DNS traffic. It keeps a list of allowed DNS lookups that can be regexps and blocks lookups that are not allowed. A singleton is always running inside cilium-agent. Note: All public fields are read only and do not require locking

func StartDNSProxy

func StartDNSProxy(address string, port uint16, lookupEPFunc LookupEndpointIDByIPFunc, notifyFunc NotifyOnDNSMsgFunc) (*DNSProxy, error)

address and port. address is the bind address to listen on. Empty binds to all local addresses. port is the port to bind to for both UDP and TCP. 0 causes the kernel to select a free port. lookupEPFunc will be called with the source IP of DNS requests, and expects a unique identifier for the endpoint that made the request. notifyFunc will be called with DNS response data that is returned to a requesting endpoint. Note that denied requests will not trigger this callback.

func (*DNSProxy) AddAllowed

func (p *DNSProxy) AddAllowed(reStr, endpointID string)

AddAllowed adds reStr, a regexp, to the DNS lookups the proxy allows.

func (*DNSProxy) CheckAllowed

func (p *DNSProxy) CheckAllowed(name, endpointID string) bool

CheckAllowed checks name against the rules added to the proxy, and only returns true if this endpointID was added (via AddAllowed) previously.

func (*DNSProxy) RemoveAllowed

func (p *DNSProxy) RemoveAllowed(reStr, endpointID string)

RemoveAllowed removes reStr from the DNS lookups the proxy allows. It must match the form in AddAllowed exactly (i.e. this isn't removing by regex, but by direct equivalence).

func (*DNSProxy) ServeDNS

func (p *DNSProxy) ServeDNS(w dns.ResponseWriter, request *dns.Msg)

ServeDNS handles individual DNS requests forwarded to the proxy, and meets the dns.Handler interface. It will:

• Look up the endpoint that sent the request by IP, via LookupEndpointIDByIP.
• Check that the endpoint ID is in the set of values associated with the DNS query (lowercased). If not, the request is dropped.
• The allowed request is forwarded to the originally intended DNS server IP
• The response is shared via NotifyOnDNSMsg (this will go to a fqdn/NameManager instance).
• Write the response to the endpoint.

func (*DNSProxy) SetRejectReply

func (p *DNSProxy) SetRejectReply(opt string)

SetRejectReply sets the default reject reply on denied dns responses.

func (*DNSProxy) UpdateAllowed

func (p *DNSProxy) UpdateAllowed(reStrToAdd, reStrToRemove []string, endpointID string)

UpdateAllowed adds and removes reStr while holding the lock. This is a bit of a hack to ensure atomic updates of rules until we replace the tracking with something better.

type LookupEndpointIDByIPFunc

type LookupEndpointIDByIPFunc func(ip net.IP) (endpoint *endpoint.Endpoint, err error)

LookupEndpointIDByIPFunc wraps logic to lookup an endpoint with any backend. See DNSProxy.LookupEndpointIDByIP for usage.

type NotifyOnDNSMsgFunc

type NotifyOnDNSMsgFunc func(lookupTime time.Time, ep *endpoint.Endpoint, epIPPort string, serverAddr string, msg *dns.Msg, protocol string, allowed bool, stat ProxyRequestContext) error

NotifyOnDNSMsgFunc handles propagating DNS response data See DNSProxy.LookupEndpointIDByIP for usage.

type ProxyRequestContext

type ProxyRequestContext struct {
	ProcessingTime spanstat.SpanStat // This is going to happen at the end of the second callback.
	// Error is a enum of [timeout, allow, denied, proxyerr].
	UpstreamTime spanstat.SpanStat
	Success      bool
	Err          error
}

ProxyRequestContext proxy dns request context struct to send in the callback

func (*ProxyRequestContext) IsTimeout

func (proxyStat *ProxyRequestContext) IsTimeout() bool

IsTimeout return true if the ProxyRequest timeout