Using name servers

Name server elements are an easy way of creating and configuring lightweight DNS server dynamically.

To create a name server element, use the following method of the Anchor interface:

	MakeNameserver(addr string) (Nameserver, error)

The creation of a new name server element results in starting a lightweight DNS server (which is serviced by the circuit daemon itself) on the respective host where the anchor lives.

If the address argument is the empty string, the DNS server will pick an available port to listen to. Otherwise, it will try to bind itself to addr.

An application error may be returned if either (i) the underlying anchor is already busy with another element, or (ii) the DNS server could not bind to the provided address parameter.

Internally, the DNS server is implemented using github.com/miekg/dns.

A name server can be stopped and discarded by either using the Scrub method of the name server element itself, or by using the Scrub method of the anchor that the name server element is attached to.

Name server elements have a simple interface:

	type Nameserver interface {
		Set(rr string) error
		Unset(name string)
		Peek() NameserverStat
		Scrub()
	}

Manipulating records

Name servers maintain a set of unique names, together with a set of records associated with each name.

New records are added using the Set method. The argument of Set is a DNS resource record in standard DNS notation. The syntax of these records are described in more detail in the documentation of github.com/miekg/dns as well as this related blog article.

Every DNS resource record, for instance "miek.nl. 3600 IN MX 10 mx.miek.nl.", starts with the name that the record pertains to. Each invocation of the Set command adds a record to the list of records pertaining to the respective name. For instance, the following command adds the record "miek.nl. 3600 IN MX 10 mx.miek.nl." to the name "miek.nl."

	if err := ns.Set("miek.nl. 3600 IN MX 10 mx.miek.nl."); err != nil {
		… // DNS record cannot be recognized
	}

The Unset method removes all records associated with a given name. For instance,

	ns.Unset("miek.nl.")

Server status

At any point, the user can asynchronously retrieve the current status of a name server element, using the Peek method of the element. The returned structure (shown below) contains a textual representation of the DNS server's address, and a map of all names and their associated lists of resource records.

	type NameserverStat struct {
		Address string
		Records map[string][]string
	}