dig

Documentation

Overview

Package dig implements a DNS FQDN-to-address digger with optional (in)validation of the network addresses dug out. The knack here is that the address digging and validation is done from within a specific network namespace (of a Docker container).

The digging and ping verification steps run concurrently, but under the constraints of limited goroutines. That is, the maximum number of each worker set is limited for DNS name-to-address resolution, as well as for address validation using ICMP pings.

Digging and pinging is implemented in pure Go, leveraging the incredible Go modules miekg/dns and go-ping/ping.

Notes

A good source for how Docker's/Moby's embedded DNS resolver works is https://github.com/moby/libnetwork/blob/master/resolver.go.

Index

• func AllFQDNsOnAttachedNetworks(nets []DockerNetwork) []string
• type Digger
  • func New(size int, netnsref string) (*Digger, chan types.NamedAddress, error)
  • func (d *Digger) DigFQDNs(ctx context.Context, names []string)
  • func (d *Digger) DigNetworks(ctx context.Context, nets []DockerNetwork)
  • func (d *Digger) StopWait()
• type DockerNetwork
• type NamedAddressSet
• type NamedAddressesMap
  • func NewNamedAddressesMap() *NamedAddressesMap
  • func (m *NamedAddressesMap) Get() []NamedAddressSet
  • func (m *NamedAddressesMap) Track(ctx context.Context, news <-chan types.NamedAddress) error
  • func (m *NamedAddressesMap) Update(namaddr types.NamedAddress)

Functions

func AllFQDNsOnAttachedNetworks

func AllFQDNsOnAttachedNetworks(nets []DockerNetwork) []string

AllFQDNsOnAttachedNetworks returns the list of FQDNs that should be addressable from a particular container, based on the list of attached networks with DNS labels and container names and aliases (also DNS labels).

A typical means to get the list of attached networks with labels and aliases might be mobynet.DiscoverAttachedNames.

Types

type Digger

type Digger struct {
	// contains filtered or unexported fields
}

Digger digs the IPv4 and IPv6 addresses of FQDNs and then streams its findings over its “news” channel.

By connecting the news (output) channel of a Verifier to the input channel of a Verifier the reachability of the addresses dug can automatically be verified by pinging them.

func New

func New(size int, netnsref string) (*Digger, chan types.NamedAddress, error)

New returns a new Digger with a maximum worker pool of the specified size as well as a “news stream”. This news channel sends NamedAddress elements as they are submitted for diggung, as well as the outcome(s) of the digs. Please note that the returned results channel is never closed by a Digger itself.

I dunno what Sir Tim, Mick, Phil, and all the others might think of our digging here...

func (*Digger) DigFQDNs

func (d *Digger) DigFQDNs(ctx context.Context, names []string)

DigFQDNs digs the given list of “host names” (whatever “host names” actually might mean). Intermediate and final results are getting sent to the channel returned beforehand by New.

func (*Digger) DigNetworks

func (d *Digger) DigNetworks(ctx context.Context, nets []DockerNetwork)

DigNetworks digs the IP addresses visible on a specific set of Docker networks. Intermediate and final results are getting sent to the channel returned beforehand by New.

func (*Digger) StopWait

func (d *Digger) StopWait()

StopWait waits for all queued tasks to get processed and then finally closes the news channel.

type DockerNetwork

type DockerNetwork struct {
	Label  string   `json:"label"`  // name of Docker network used as DNS "TLD" label.
	Labels []string `json:"labels"` // container and service/alias names used as DNS labels.
}

DockerNetwork describes a single Docker network in terms of its name, as well as the DNS labels of the attached containers and associated service names.

type NamedAddressSet

type NamedAddressSet struct {
	FQDN      string                        `json:"fqdn"`      // the DNS "name"
	Addresses []types.QualifiedAddressValue `json:"addresses"` // associated IP network address(es)
}

NamedAddressSet is a DNS FQDN together with a list of associated/resolved qualified network addresses.

type NamedAddressesMap

type NamedAddressesMap struct {
	// contains filtered or unexported fields
}

NamedAddressesMap maps DNS FQDNs to their corresponding lists of qualified IP addresses. A typical use case for a NamedAddressMap is to consume name-address information from an event stream (channel) sending updates as names are discovered, resolved into the corresponding IP addresses, and finally (in)validated.

func NewNamedAddressesMap

func NewNamedAddressesMap() *NamedAddressesMap

NewNamedAddressesMap returns a new and properly initialized NamedAddressesMap.

func (*NamedAddressesMap) Get

func (m *NamedAddressesMap) Get() []NamedAddressSet

Get returns all named addresses from the map.

func (*NamedAddressesMap) Track

func (m *NamedAddressesMap) Track(ctx context.Context, news <-chan types.NamedAddress) error

Track NamedAddress updates received from the specified update channel until the channel is closed or the context done. Track only returns after processing all updates or when the context is done.

func (*NamedAddressesMap) Update

func (m *NamedAddressesMap) Update(namaddr types.NamedAddress)

Update the map with a NamedAddress, augmenting addresses in case they are yet unknown. Known addresses are updated in case they have quality changing as follows:

• from unverified to verifying
• from verifying to either verified or invalid