5.9 KiB
API
Generated from the package comment and every exported declaration. Do not edit.
Regenerate with UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1.
Package godns
Package godns is a library for authoritative DNS against BIND-compatible nameservers: full zone transfer (AXFR) over TCP and RFC 2136 dynamic UPDATE, authenticated with caller-supplied TSIG. Domain names are ASCII only in v1.
Types
Action
type Action int
Action is one RFC 2136 UPDATE operation.
ActionAdd
ActionDelete
const (
// ActionAdd inserts a record.
ActionAdd Action = iota
// ActionDelete removes one record that matches owner, type, and rdata.
ActionDelete
)
Change
type Change struct {
Action Action
Record Record
}
Change is one add or delete of one record inside an Update batch.
Add
func Add(rec Record) Change
Add builds an insert change for rec.
Delete
func Delete(rec Record) Change
Delete builds a delete of one matching record (owner, type, and rdata).
Client
type Client struct {
// contains filtered or unexported fields
}
Client is one session: one nameserver, one zone, and one TSIG key. AXFR and Update both use that key. There is no unsigned mode.
NewClient
func NewClient(server, zone string, key TSIG) (*Client, error)
NewClient starts a session for one nameserver, zone, and TSIG key. server is a host or host:port. A missing port becomes 53. An IPv6 host must be written in brackets. It returns an error when server, zone, or any TSIG field is empty, when zone or the key name is not ASCII, or when server is a bare IPv6 address.
Client.AXFR
func (c *Client) AXFR(ctx context.Context) (*TransferResult, error)
AXFR reads the full zone over TCP, signed with the session TSIG key. It returns an error when ctx is done, the transfer fails, a record owner is not ASCII, or the stream contains no SOA. The closing SOA of the transfer is not appended again.
Client.Update
func (c *Client) Update(ctx context.Context, changes ...Change) (*UpdateResult, error)
Update sends an RFC 2136 UPDATE for changes, signed with the session TSIG key. It tries UDP, then TCP when the UDP exchange fails or the response is truncated. No changes returns success and does not contact the nameserver. It returns an error when ctx is done, a record cannot be encoded, the exchange fails, the nameserver rcode is not NOERROR, or Action is neither ActionAdd nor ActionDelete.
RRSet
type RRSet struct {
Owner string
Class string
Type string
Records []Record
}
RRSet groups records that share owner, class, and type.
Record
type Record struct {
Owner string
Class string
Type string
TTL uint32
RData string
}
Record is one resource record. Owner is a trailing-dot FQDN. Class and Type are presentation names such as IN and A. RData is the presentation-format rdata, without the owner, TTL, class, or type.
A
func A(owner string, ttl uint32, ip net.IP) (Record, error)
A builds an IN A record. It returns an error when ip is not IPv4, or when owner is empty or not ASCII. Owner is stored as a trailing-dot FQDN.
AAAA
func AAAA(owner string, ttl uint32, ip net.IP) (Record, error)
AAAA builds an IN AAAA record. It returns an error when ip is missing, is IPv4, or when owner is empty or not ASCII. Owner is stored as a trailing-dot FQDN.
CAA
func CAA(owner string, ttl uint32, flag uint8, tag, value string) (Record, error)
CAA builds an IN CAA record (RFC 8659) with flag, tag, and value. It returns an error when owner is empty or not ASCII.
CNAME
func CNAME(owner string, ttl uint32, target string) (Record, error)
CNAME builds an IN CNAME record pointing at target. It returns an error when owner or target is empty or not ASCII.
MX
func MX(owner string, ttl uint32, pref uint16, target string) (Record, error)
MX builds an IN MX record for preference pref and exchanger target. It returns an error when owner or target is empty or not ASCII.
NS
func NS(owner string, ttl uint32, target string) (Record, error)
NS builds an IN NS record pointing at target. It returns an error when owner or target is empty or not ASCII.
PTR
func PTR(owner string, ttl uint32, target string) (Record, error)
PTR builds an IN PTR record pointing at target. It returns an error when owner or target is empty or not ASCII.
SRV
func SRV(owner string, ttl uint32, prio, weight, port uint16, target string) (Record, error)
SRV builds an IN SRV record. It returns an error when owner or target is empty or not ASCII.
TXT
func TXT(owner string, ttl uint32, text string) (Record, error)
TXT builds an IN TXT record whose rdata is text. It returns an error when owner is empty or not ASCII.
TSIG
type TSIG struct {
Name string
Algorithm string
Secret string
}
TSIG is caller-supplied key material. The library does not generate keys or write BIND configuration. Name is the key name presented to the nameserver. Algorithm is a BIND name such as hmac-sha256 (also hmac-md5, hmac-sha1, hmac-sha224, hmac-sha384, and hmac-sha512). Secret is the base64 secret.
TransferResult
type TransferResult struct {
Zone Zone
Serial uint32
}
TransferResult is a completed AXFR. Serial is the SOA serial and is the same value stored on Zone.
UpdateResult
type UpdateResult struct {
Rcode string
}
UpdateResult is a successful UPDATE response. Rcode is the nameserver rcode text, which is NOERROR on success.
Zone
type Zone struct {
Origin string
Serial uint32
Records []Record
}
Zone is an in-memory zone: origin, SOA serial, and a flat record list. AXFR returns one. Callers can also assemble a Zone and call RRSets.
Zone.RRSets
func (z Zone) RRSets() []RRSet
RRSets groups Zone records by owner, class, and type, in first-seen order.