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, enableDNSCompression bool, maxRestoreDNSIPs int, ...) (*DNSProxy, error)
  • func (p *DNSProxy) CheckAllowed(endpointID uint64, destPort uint16, destID identity.NumericIdentity, ...) (allowed bool, err error)
  • func (p *DNSProxy) GetRules(endpointID uint16) restore.DNSRules
  • func (p *DNSProxy) LookupEndpointByIP(ip net.IP) (endpoint *endpoint.Endpoint, err error)
  • func (p *DNSProxy) RemoveRestoredRules(endpointID uint16)
  • func (p *DNSProxy) RestoreRules(ep *endpoint.Endpoint)
  • func (p *DNSProxy) ServeDNS(w dns.ResponseWriter, request *dns.Msg)
  • func (p *DNSProxy) SetRejectReply(opt string)
  • func (p *DNSProxy) UpdateAllowed(endpointID uint64, destPort uint16, newRules policy.L7DataMap) error
• type LookupEndpointIDByIPFunc
• type LookupIPsBySecIDFunc
• type LookupSecIDByIPFunc
• 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

	// LookupRegisteredEndpoint is a provided callback that returns the endpoint ID
	// as a uint16.
	// 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.
	LookupRegisteredEndpoint LookupEndpointIDByIPFunc

	// LookupSecIDByIP is a provided callback that returns the IP's security ID
	// from the ipcache.
	// 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.
	LookupSecIDByIP LookupSecIDByIPFunc

	// LookupIPsBySecID is a provided callback that returns the IPs by security ID
	// from the ipcache.
	LookupIPsBySecID LookupIPsBySecIDFunc

	// 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

	// EnableDNSCompression allows the DNS proxy to compress responses to
	// endpoints that are larger than 512 Bytes or the EDNS0 option, if present.
	EnableDNSCompression bool

	// 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, enableDNSCompression bool, maxRestoreDNSIPs int, lookupEPFunc LookupEndpointIDByIPFunc, lookupSecIDFunc LookupSecIDByIPFunc, lookupIPsFunc LookupIPsBySecIDFunc, notifyFunc NotifyOnDNSMsgFunc) (*DNSProxy, error)

StartDNSProxy starts a proxy used for DNS L7 redirects that listens on 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) CheckAllowed

func (p *DNSProxy) CheckAllowed(endpointID uint64, destPort uint16, destID identity.NumericIdentity, destIP net.IP, name string) (allowed bool, err error)

CheckAllowed checks endpointID, destPort, destID, destIP, and name against the rules added to the proxy or restored during restart, and only returns true if this all match something that was added (via UpdateAllowed or RestoreRules) previously.

func (*DNSProxy) GetRules

func (p *DNSProxy) GetRules(endpointID uint16) restore.DNSRules

GetRules creates a fresh copy of EP's DNS rules to be stored for later restoration.

func (*DNSProxy) LookupEndpointByIP

func (p *DNSProxy) LookupEndpointByIP(ip net.IP) (endpoint *endpoint.Endpoint, err error)

LookupEndpointByIP wraps LookupRegisteredEndpoint by falling back to an restored EP, if available

func (*DNSProxy) RemoveRestoredRules

func (p *DNSProxy) RemoveRestoredRules(endpointID uint16)

RemoveRestoredRules removes all restored rules for 'endpointID'.

func (*DNSProxy) RestoreRules

func (p *DNSProxy) RestoreRules(ep *endpoint.Endpoint)

RestoreRules is used in the beginning of endpoint restoration to install rules saved before the restart to be used before the endpoint is regenerated. 'ep' passed in is not fully functional yet, but just unmarshaled from JSON!

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 LookupEndpointByIP.
• Look up the Sec ID of the destination server, via LookupSecIDByIP.
• Check that the endpoint ID, destination Sec ID, destination port and the qname all match a rule. 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(endpointID uint64, destPort uint16, newRules policy.L7DataMap) error

UpdateAllowed sets newRules for endpointID and destPort. It compiles the DNS rules into regexes that are then used in CheckAllowed.

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.LookupRegisteredEndpoint for usage.

type LookupIPsBySecIDFunc

type LookupIPsBySecIDFunc func(nid identity.NumericIdentity) []string

LookupIPsBySecIDFunc Func wraps logic to lookup an IPs by security ID from the ipcache.

type LookupSecIDByIPFunc

type LookupSecIDByIPFunc func(ip net.IP) (secID ipcache.Identity, exists bool)

LookupSecIDByIPFunc Func wraps logic to lookup an IP's security ID from the ipcache. See DNSProxy.LookupSecIDByIP 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