Update the readme

README.markdown

@@ -7,13 +7,13 @@ supported, including the DNSSEC types. It follows a lean and mean philosophy.
 If there is stuff you should know as a DNS programmer there isn't a convenience
 function for it. 
 
-Goals:
+## Goals:
 
 * KISS;
 * Symmetric API: client and server side should be very similar;
 * Small API, if its easy to code in Go, don't make a function for it.
 
-Features:
+## Features:
 
 * UDP/TCP queries, IPv4 and IPv6;
 * RFC 1035 zone file parsing;
@@ -29,6 +29,12 @@ Features:
 * TSIG;
 * DNS name compression.
 
+Have fun!
+
+Miek Gieben  -  2010-2012 - miek@miek.nl
+
+## Building
+
 Building is done with the `go` tool. If you have setup your GOPATH
 correctly the following should work:
 
@@ -37,9 +43,60 @@ correctly the following should work:
 Sample programs can be found in the `ex` directory. They can 
 be build with: `make -C ex`, or also with the `go` tool.
 
-Have fun!
+## Building (from scratch)
 
-Miek Gieben  -  2010-2012 - miek@miek.nl
+The development of the language [Go](http://www.golang.org) is
+going at a fast pace, hence an updated version of
+[Super-short guide to gettinq](http://www.miek.nl/blog/archives/2012/01/23/super-short_guide_to_getting_q/index.html).
+
+Get the latest version (called `weekly`) of Go:
+
+1. Get Go: `hg clone -u release https://go.googlecode.com/hg/ go`
+   Note the directory you have downloaded it to and set add its `bin`
+   directory to your PATH: `PATH=$PWD/go/bin`.
+
+2. Update Go to the latest weekly: `cd go; hg pull; hg update weekly`
+
+3. Compile Go: `cd src`, you should now sit in `go/src`.
+   And compile: `./all.bash`
+
+>    Install missing commands (gcc, sed, bison, etc.) if needed.
+
+The latest Go is now installed. You should now have the `go`-tool,
+this is the central interface to all Go program building tasks.
+
+    $ go
+    Go is a tool for managing Go source code.
+
+    Usage: go command [arguments]
+
+    The commands are:
+
+    build       compile packages and dependencies
+    clean       remove object files
+    doc         run godoc on package sources
+    fix         run go tool fix on packages
+    ....
+    ....
+    lost more
+
+If you can not run `go`, check your PATH.
+
+### Install Go DNS and set GOPATH
+
+The GOPATH variable specifies (among things) where *your* GO
+code lives. Using the `go` tool does bring a few requirement
+to the table in how to layout the directory structure.
+
+1. Create toplevel directory (`~/g`)for your code: `mkdir -p ~/g/src`
+2. Set GOPATH to this toplevel directory: `export GOPATH=~/g`
+1. Get dns: `cd ~/g/src; git clone git://github.com/miekg/dns.git`
+2. Compile it: `cd dns; go build`
+3. Compile and install the examples, there is a helper `Makefile` here, but it
+   just calls `go` multiple times: `cd ex; make`
+4. Look in `$GOPATH/bin` for the binaries, in this setup that will be `~/g/bin`
+4. Query with q: `~/g/bin/q mx miek.nl` (or add `~/g/bin` to your $PATH too)
+5. Report bugs
 
 ## Supported RFCs
 

defaults.go

@@ -84,12 +84,12 @@ func (dns *Msg) SetAxfr(z string) {
 // This is only a skeleton Tsig RR that is added as the last RR in the 
 // additional section. The caller should then call TsigGenerate, 
 // to generate the complete TSIG with the secret.
-func (dns *Msg) SetTsig(z, algo string, fudge uint16, timesigned uint64) {
+func (dns *Msg) SetTsig(z, algo string, fudge uint16, timesigned int64) {
 	t := new(RR_TSIG)
 	t.Hdr = RR_Header{z, TypeTSIG, ClassANY, 0, 0}
 	t.Algorithm = algo
 	t.Fudge = 300
-	t.TimeSigned = timesigned
+	t.TimeSigned = uint64(timesigned)
 	dns.Extra = append(dns.Extra, t)
 }
 

ex/axfr/axfr.go

@@ -4,12 +4,14 @@ import (
 	"dns"
 	"flag"
 	"fmt"
+	"strings"
+	"time"
 )
 
 func main() {
-	var serial *int = flag.Int("serial", 0, "Perform an IXFR with the given serial")
-	var nameserver *string = flag.String("ns", "127.0.0.1:53", "Query this nameserver")
-	//	var secret *string = flag.String("secret", "", "Use this secret for TSIG")
+	serial := flag.Int("serial", 0, "Perform an IXFR with the given serial")
+	nameserver := flag.String("ns", "127.0.0.1:53", "Query this nameserver")
+	tsig := flag.String("tsig", "", "request tsig with key: name:key (only hmac-sha1)")
 	flag.Parse()
 	zone := flag.Arg(flag.NArg() - 1)
 
@@ -21,6 +23,13 @@ func main() {
 	} else {
 		m.SetAxfr(zone)
 	}
+	if *tsig != "" {
+		a := strings.SplitN(*tsig, ":", 2)
+		name, secret := a[0], a[1]
+		client.TsigSecret = map[string]string{name: secret}
+		m.SetTsig(name, dns.HmacSHA1, 300, time.Now().Unix())
+	}
+
 	if err := client.XfrReceive(m, *nameserver); err == nil {
 		for r := range client.ReplyChan {
 			if r.Error != nil {

ex/q/q.go

@@ -166,7 +166,7 @@ Flags:
 		// Add tsig
 		if *tsig != "" {
 			if algo, name, secret, ok := tsigKeyParse(*tsig); ok {
-				m.SetTsig(name, algo, 300, uint64(time.Now().Unix()))
+				m.SetTsig(name, algo, 300, time.Now().Unix())
 				c.TsigSecret = map[string]string{name: secret}
 			} else {
 				fmt.Fprintf(os.Stderr, "TSIG key error\n")

tsig.go

@@ -1,15 +1,14 @@
 // TRANSACTION SIGNATURE (TSIG)
 // 
 // An TSIG or transaction signature adds a HMAC TSIG record to each message sent. 
-// Basic use pattern when querying with TSIG:
+// Basic use pattern when querying with a TSIG name "axfr." and the base64
+// secret "so6ZGir4GPAqINNh9U5c3A==":
 //
 //	m := new(Msg)
 //	c := NewClient()
 //	m.SetQuestion("miek.nl.", TypeMX)
-//	// Set the secret under the name "axfr."
-//	c.TsigSecret = map[string]string{"axfr.": "so6ZGir4GPAqINNh9U5c3A=="}	// don't forget the .
-//	// Add the stub TSIG RR to the message
-//	m.SetTsig("axfr.", HmacMD5, 300, uint64(time.Seconds()))
+//	m.SetTsig("axfr.", HmacMD5, 300, time.Now().Unix())
+//	c.TsigSecret = map[string]string{"axfr.": "so6ZGir4GPAqINNh9U5c3A=="}
 //	...
 //	// When sending the TSIG RR is calculated and filled in before sending
 //
@@ -24,6 +23,7 @@
 //	c := NewClient()
 //	m := New(Msg)
 //	m.SetAxfr("miek.nl.") 
+//	m.SetTsig("axfr.", HmacMD5, 300, time.Now().Unix())
 //	c.TsigSecret = map[string]string{"axfr.": "so6ZGir4GPAqINNh9U5c3A=="}
 //	err := c.XfrReceive(m, "85.223.71.124:53")
 //