From 6f78219c22b98c270744c5fe97d5d154a9a9d7d9 Mon Sep 17 00:00:00 2001 From: Miek Gieben Date: Sun, 11 Sep 2011 20:47:25 +0200 Subject: [PATCH] Documentation updates --- dns.go | 12 ++++++-- tsig.go | 10 +++++-- update.go | 85 +++++++++++++++++++++++++++++++++++++------------------ xfr.go | 2 -- 4 files changed, 75 insertions(+), 34 deletions(-) diff --git a/dns.go b/dns.go index 9803b3d8..e9395c5e 100644 --- a/dns.go +++ b/dns.go @@ -3,6 +3,8 @@ // license that can be found in the LICENSE file. // Extended and bugfixes by Miek Gieben. +// DOMAIN NAME SYSTEM +// // Package dns implements a full featured interface to the Domain Name System. // The package allows complete control over what is send out to the DNS. // @@ -25,16 +27,19 @@ // m := new(Msg) // m.SetQuestion("miek.nl.", TypeMX) // -// Or slightly more verbose, but more flexible: +// The message m is now a messages with the Question section set to ask +// the MX records for the miek.nl. zone. +// +// This is slightly more verbose, but more flexible: // // m1 := new(Msg) // m1.MsgHdr.Id = Id() // m1.MsgHdr.RecursionDesired = false // m1.Question = make([]Question, 1) -// m1.Question[0] = Question{"miek.nl", TypeDNSKEY, ClassINET} +// m1.Question[0] = Question{"miek.nl", TypeMX, ClassINET} // // After creating a message it can be send. -// Basic use pattern for synchronous querying the DNS, here +// Basic use pattern for synchronous querying the DNS. We are // sending the message 'm' to the server 127.0.0.1 on port 53 and // waiting for the reply. // @@ -42,6 +47,7 @@ // // c.Net = "tcp" // If you want to use TCP // in := c.Exchange(m, "127.0.0.1:53") // +// An asynchronous query ... TODO(mg) package dns import ( diff --git a/tsig.go b/tsig.go index 31cc936b..c57de8ec 100644 --- a/tsig.go +++ b/tsig.go @@ -1,4 +1,6 @@ -// TSIG or transaction signature adds a HMAC TSIG record to each message sent. +// TRANSACTION SIGNATURE (TSIG) +// +// A TSIG or transaction signature adds a HMAC TSIG record to each message sent. // Basic use pattern when querying with TSIG: // // m := new(Msg) @@ -11,7 +13,11 @@ // secrets := make(map[string]string) // secrets["axfr."] = "so6ZGir4GPAqINNh9U5c3A==" // don't forget the . here // -// The message requesting an AXFR for miek.nl with the TSIG record added is now ready to use. +// The secrets' map index is set to 'axfr.'. This must match the ownername of the +// TSIG records, which in the above example, is also set to 'axfr.' +// +// The message requesting an AXFR (almost all TSIG usage is when requesting zone transfers) +// for miek.nl with the TSIG record added is now ready to use. // We now need a new client with access to the secrets: // // c := NewClient() diff --git a/update.go b/update.go index bcdc83bc..588c478f 100644 --- a/update.go +++ b/update.go @@ -1,14 +1,41 @@ +// DYNAMIC UPDATES +// +// Dynamic updates reuses the DNS message format, but renames the three of +// the sections. Question is Zone, Answer is Prerequisite, Authority is +// Update, only the Additional is not renamed. See RFC 2136 for the gory details. +// +// You can set a rather complex set of rules for the existence of absence of +// certain resource records or names in a zone to specify if resource records +// should be added or removed. The table from RFC 2136 supplemented with the Go +// DNS function shows which functions exist to specify the prerequisites. +// +// 3.2.4 - Table Of Metavalues Used In Prerequisite Section +// +// CLASS TYPE RDATA Meaning Function +// ---------------------------------------------------------------------------- +// ANY ANY empty Name is in use NameUsed +// ANY rrset empty RRset exists (value independent) RRsetUsedNoRdata +// NONE ANY empty Name is not in use NameNotUsed +// NONE rrset empty RRset does not exist RRsetNotUsed +// zone rrset rr RRset exists (value dependent) RRsetUsedRdata +// +// The prerequisite section can also be left empty. +// If you have decided an the prerequisites you can tell what RRs should +// be added or deleted. The next table shows the options you have and +// what function to call. +// 3.4.2.6 - Table Of Metavalues Used In Update Section +// +// CLASS TYPE RDATA Meaning Function +// ------------------------------------------------------------------------- +// ANY ANY empty Delete all RRsets from a name NameDelete +// ANY rrset empty Delete an RRset RRsetDelete +// NONE rrset rr Delete an RR from an RRset RRsetDeleteRR +// zone rrset rr Add to an RRset RRsetAddRdata +// package dns -// Implements wrapper functions for dealing with dynamic update packets. -// Dynamic update packets are identical to normal DNS messages, but the -// names are redefined. See RFC 2136 for the details. - type Update struct{ Msg } -// Not sure if I want to keep these functions, but they -// may help a programmer - func (u *Update) Zone() []Question { return u.Msg.Question } @@ -34,15 +61,17 @@ func NewUpdate(zone string, class uint16) *Update { return u } +// The table from RFC 2136 supplemented with the Go DNS function. +// // 3.2.4 - Table Of Metavalues Used In Prerequisite Section // -// CLASS TYPE RDATA Meaning -// ------------------------------------------------------------ -// ANY ANY empty Name is in use -// ANY rrset empty RRset exists (value independent) -// NONE ANY empty Name is not in use -// NONE rrset empty RRset does not exist -// zone rrset rr RRset exists (value dependent) +// CLASS TYPE RDATA Meaning Function +// ---------------------------------------------------------------------- +// ANY ANY empty Name is in use NameUsed +// ANY rrset empty RRset exists (value independent) RRsetUsedNoRdata +// NONE ANY empty Name is not in use NameNotUsed +// NONE rrset empty RRset does not exist RRsetNotUsed +// zone rrset rr RRset exists (value dependent) RRsetUsedRdata // NameUsed sets the RRs in the prereq section to // "Name is in use" RRs. RFC 2136 section 2.4.4. @@ -62,9 +91,9 @@ func (u *Update) NameNotUsed(rr []RR) { } } -// RRsetUsedFull sets the RRs in the prereq section to +// RRsetUsedRdata sets the RRs in the prereq section to // "RRset exists (value dependent -- with rdata)" RRs. RFC 2136 section 2.4.2. -func (u *Update) RRsetUsedFull(rr []RR) { +func (u *Update) RRsetUsedRdata(rr []RR) { if len(u.Msg.Question) == 0 { panic("empty question section") } @@ -75,9 +104,9 @@ func (u *Update) RRsetUsedFull(rr []RR) { } } -// RRsetUsed sets the RRs in the prereq section to +// RRsetUsedNoRdata sets the RRs in the prereq section to // "RRset exists (value independent -- no rdata)" RRs. RFC 2136 section 2.4.1. -func (u *Update) RRsetUsed(rr []RR) { +func (u *Update) RRsetUsedNoRdata(rr []RR) { u.Answer = make([]RR, len(rr)) for i, r := range rr { u.Answer[i] = r @@ -99,17 +128,19 @@ func (u *Update) RRsetNotUsed(rr []RR) { } } +// The table from RFC 2136 supplemented with the Go DNS function. +// // 3.4.2.6 - Table Of Metavalues Used In Update Section // -// CLASS TYPE RDATA Meaning -// --------------------------------------------------------- -// ANY ANY empty Delete all RRsets from a name -// ANY rrset empty Delete an RRset -// NONE rrset rr Delete an RR from an RRset -// zone rrset rr Add to an RRset +// CLASS TYPE RDATA Meaning Function +// -------------------------------------------------------------------------- +// ANY ANY empty Delete all RRsets from a name NameDelete +// ANY rrset empty Delete an RRset RRsetDelete +// NONE rrset rr Delete an RR from an RRset RRsetDeleteRR +// zone rrset rr Add to an RRset RRsetAddRdata -// RRsetAddFull adds an complete RRset, see RFC 2136 section 2.5.1 -func (u *Update) RRsetAddFull(rr []RR) { +// RRsetAddRdata adds an complete RRset, see RFC 2136 section 2.5.1 +func (u *Update) RRsetAddRdata(rr []RR) { if len(u.Msg.Question) == 0 { panic("empty question section") } @@ -120,7 +151,7 @@ func (u *Update) RRsetAddFull(rr []RR) { } } -// RRsetDelete delete an RRset, see RFC 2136 section 2.5.2 +// RRsetDelete deletes an RRset, see RFC 2136 section 2.5.2 func (u *Update) RRsetDelete(rr []RR) { u.Ns = make([]RR, len(rr)) for i, r := range rr { diff --git a/xfr.go b/xfr.go index b3fcc5cc..a417e010 100644 --- a/xfr.go +++ b/xfr.go @@ -115,8 +115,6 @@ func (w *reply) ixfrReceive() { panic("not reached") return } -// TODO(mg): helper function for settings/making/parsing the -// packets gotten from/to the ixfr/axfr functions // XfrSend performs an outgoing Ixfr or Axfr. If the message q's question // section contains an AXFR type an Axfr is performed. If it is IXFR