dns/README.markdown

# Alternative (more granular) approach to a DNS library.

> Less is more.

Complete and usable DNS library. All widely used Resource Records are
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. Server side and client side programming is supported, i.e. you
can build servers and resolvers with it.

If you like this, you may also be interested in:

* https://github.com/miekg/fks -- a (in)complete nameserver written in Go;
* https://github.com/miekg/unbound -- Go wrapper for the Unbound resolver.

# Goals

* KISS;
* Fast
* Small API, if its easy to code in Go, don't make a function for it.

# Users

A not-so-up-to-date-list-that-may-be-actually-current:

* https://github.com/abh/geodns
* http://www.statdns.com/
* http://www.dnsinspect.com/
* https://github.com/chuangbo/jianbing-dictionary-dns
* http://www.dns-lg.com/
* https://github.com/fcambus/rrda
* https://github.com/kenshinx/godns
* more? (send pull request if you want to be listed here)

# Features

* UDP/TCP queries, IPv4 and IPv6;
* RFC 1035 zone file parsing ($INCLUDE, $ORIGIN, $TTL and $GENERATE (for all record types) are supported;
* Fast:
    * Reply speed around ~ 80K qps (faster hardware results in more qps);
    * Parsing RRs with  ~ 100K RR/s, that's 5M records in about 50 seconds;
* Server side programming (mimicking the net/http package);
* Client side programming;
* DNSSEC: signing, validating and key generation for DSA, RSA and ECDSA;
* EDNS0, NSID;
* AXFR/IXFR;
* 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:

    go get github.com/miekg/dns
    go build github.com/miekg/dns

A short "how to use the API" is at the beginning of dns.go (this also will show
when you call `go doc github.com/miekg/dns`. Sample
programs can be found in the `ex` directory. They can also be build
with: `go build`.

## Supported RFCs

*all of them*

* 103{4,5} - DNS standard
* 1982 - Serial Arithmetic
* 1876 - LOC record
* 1995 - IXFR
* 1996 - DNS notify
* 2136 - DNS Update (dynamic updates)
* 2181 - RRset definition
* 2537 - RSAMD5 DNS keys
* 2065 - DNSSEC (updated in later RFCs)
* 2671 - EDNS record
* 2782 - SRV record
* 2845 - TSIG record
* 2915 - NAPTR record
* 2929 - DNS IANA Considerations
* 3110 - RSASHA1 DNS keys
* 3225 - DO bit (DNSSEC OK)
* 340{1,2,3} - NAPTR record
* 3445 - Limiting the scope of (DNS)KEY
* 3597 - Unkown RRs
* 403{3,4,5} - DNSSEC + validation functions
* 4255 - SSHFP record
* 4343 - Case insensitivity
* 4408 - SPF record
* 4509 - SHA256 Hash in DS
* 4592 - Wildcards in the DNS
* 4635 - HMAC SHA TSIG
* 4701 - DHCID
* 4892 - id.server
* 5001 - NSID
* 5155 - NSEC3 record
* 5205 - HIP record
* 5702 - SHA2 in the DNS
* 5936 - AXFR
* 6605 - ECDSA
* 6742 - ILNP DNS
* 6891 - EDNS0 update
* xxxx - URI record (draft)
* xxxx - EDNS0 DNS Update Lease (draft)
* xxxx - IEU48/IEU64 records (draft)
* xxxx - Algorithm-Signal (draft)

## Loosely based upon

* `ldns`
* `NSD`
* `Net::DNS`
* `GRONG`
tweaks 2011-02-10 08:01:43 +00:00			`# Alternative (more granular) approach to a DNS library.`
update the readme a little 2010-12-28 14:44:19 +00:00
tweaks 2012-01-28 00:14:55 +00:00			`> Less is more.`

Update the readme 2012-05-03 06:59:02 +00:00			`Complete and usable DNS library. All widely used Resource Records are`
Small tweaks 2012-01-27 07:51:24 +00:00			`supported, including the DNSSEC types. It follows a lean and mean philosophy.`
Update the readme 2012-01-11 21:01:40 +00:00			`If there is stuff you should know as a DNS programmer there isn't a convenience`
Update the readme 2012-05-03 06:59:02 +00:00			`function for it. Server side and client side programming is supported, i.e. you`
			`can build servers and resolvers with it.`
Make the readme more readable 2011-07-05 17:54:20 +00:00
Update readme 2012-08-09 21:38:47 +00:00			`If you like this, you may also be interested in:`

Fix doc and todo 2013-06-23 20:39:14 +00:00			`* https://github.com/miekg/fks -- a (in)complete nameserver written in Go;`
Update readme 2012-08-09 21:38:47 +00:00			`* https://github.com/miekg/unbound -- Go wrapper for the Unbound resolver.`

update readme 2012-05-11 21:48:43 +00:00			`# Goals`
Make github understand the list 2012-02-15 09:34:35 +00:00
update the readme 2012-01-26 22:00:37 +00:00			`* KISS;`
small doc updates 2013-05-15 23:15:36 +00:00			`* Fast`
small update 2012-02-19 12:38:31 +00:00			`* Small API, if its easy to code in Go, don't make a function for it.`
update the readme 2012-01-26 22:00:37 +00:00
List the users of this list 2013-03-14 15:42:35 +00:00			`# Users`

			`A not-so-up-to-date-list-that-may-be-actually-current:`

			`* https://github.com/abh/geodns`
			`* http://www.statdns.com/`
			`* http://www.dnsinspect.com/`
update the readme a bit 2013-08-26 04:22:11 +00:00			`* https://github.com/chuangbo/jianbing-dictionary-dns`
Adding some projects to the list of library users 2013-07-04 17:09:37 +00:00			`* http://www.dns-lg.com/`
			`* https://github.com/fcambus/rrda`
a new user of dns library in go 2013-07-26 16:50:20 +00:00			`* https://github.com/kenshinx/godns`
update the readme a bit 2013-08-26 04:22:11 +00:00			`* more? (send pull request if you want to be listed here)`
List the users of this list 2013-03-14 15:42:35 +00:00
update readme 2012-05-11 21:48:43 +00:00			`# Features`
Make the readme more readable 2011-07-05 17:54:20 +00:00
update readme and fix spelling mistakes 2011-09-12 08:13:50 +00:00			`* UDP/TCP queries, IPv4 and IPv6;`
small doc updates 2013-05-15 23:15:36 +00:00			`* RFC 1035 zone file parsing ($INCLUDE, $ORIGIN, $TTL and $GENERATE (for all record types) are supported;`
Update readme 2013-05-05 19:59:43 +00:00			`* Fast:`
			`* Reply speed around ~ 80K qps (faster hardware results in more qps);`
again we are faster 2012-10-15 11:44:18 +00:00			`* Parsing RRs with ~ 100K RR/s, that's 5M records in about 50 seconds;`
Update readme 2012-08-09 21:38:47 +00:00			`* Server side programming (mimicking the net/http package);`
more inline with what we support 2012-11-19 18:28:49 +00:00			`* Client side programming;`
Update the readme 2012-05-03 06:59:02 +00:00			`* DNSSEC: signing, validating and key generation for DSA, RSA and ECDSA;`
Tell about the new coolness in the README 2012-02-13 21:02:36 +00:00			`* EDNS0, NSID;`
update readme and fix spelling mistakes 2011-09-12 08:13:50 +00:00			`* AXFR/IXFR;`
NSEC3 encoding works Only for 1 windows, but dig has stopped complaining. This needs to be streamlined a little, but its looking good. 2012-01-14 10:08:42 +00:00			`* TSIG;`
update the readme 2012-01-26 22:00:37 +00:00			`* DNS name compression.`
update the readme a little 2010-12-28 14:44:19 +00:00
Update the readme 2012-03-04 15:35:21 +00:00			`Have fun!`

small tweaks 2012-05-20 18:46:25 +00:00			`Miek Gieben - 2010-2012 - miek@miek.nl`
Update the readme 2012-03-04 15:35:21 +00:00
update readme 2012-05-11 21:48:43 +00:00			`# Building`
Update the readme 2012-03-04 15:35:21 +00:00
Update the README for the new Makefile-less situation 2012-02-05 10:04:21 +00:00			Building is done with the `go` tool. If you have setup your GOPATH
Add comma 2012-12-02 07:13:57 +00:00			`correctly, the following should work:`
more more more 2011-01-01 21:07:47 +00:00
Update readme 2012-08-09 21:38:47 +00:00			`go get github.com/miekg/dns`
Fix "go build" path typo. 2013-10-07 20:02:55 +00:00			`go build github.com/miekg/dns`
Update the README for the new Makefile-less situation 2012-02-05 10:04:21 +00:00
Add comments from Stephan 2012-12-01 20:29:47 +00:00			`A short "how to use the API" is at the beginning of dns.go (this also will show`
			when you call `go doc github.com/miekg/dns`. Sample
			programs can be found in the `ex` directory. They can also be build
			with: `go build`.
Whitespace cleanup 2013-09-20 15:15:27 +00:00
Doc 2012-01-15 15:29:01 +00:00			`## Supported RFCs`
documentation updates 2011-01-27 08:29:11 +00:00
Update the readme 2012-05-03 06:59:02 +00:00			`all of them`
update the readme 2012-01-26 22:00:37 +00:00
docs 2012-08-26 20:32:47 +00:00			`* 103{4,5} - DNS standard`
documentation updates 2011-01-27 08:29:11 +00:00			`* 1982 - Serial Arithmetic`
LOC record support, more complete 2012-04-30 13:47:37 +00:00			`* 1876 - LOC record`
documentation updates 2011-01-27 08:29:11 +00:00			`* 1995 - IXFR`
			`* 1996 - DNS notify`
add panics to update if q section is empty 2011-08-24 13:39:26 +00:00			`* 2136 - DNS Update (dynamic updates)`
documentation updates 2011-01-27 08:29:11 +00:00			`* 2181 - RRset definition`
			`* 2537 - RSAMD5 DNS keys`
			`* 2065 - DNSSEC (updated in later RFCs)`
add URI record 2012-02-18 20:49:02 +00:00			`* 2671 - EDNS record`
			`* 2782 - SRV record`
			`* 2845 - TSIG record`
			`* 2915 - NAPTR record`
Add another rfc to the list 2013-04-18 09:23:53 +00:00			`* 2929 - DNS IANA Considerations`
documentation updates 2011-01-27 08:29:11 +00:00			`* 3110 - RSASHA1 DNS keys`
			`* 3225 - DO bit (DNSSEC OK)`
add URI record 2012-02-18 20:49:02 +00:00			`* 340{1,2,3} - NAPTR record`
Check the protocol value of the key 2012-02-16 22:34:09 +00:00			`* 3445 - Limiting the scope of (DNS)KEY`
add unknown rr rfc 2011-02-21 15:24:14 +00:00			`* 3597 - Unkown RRs`
make the supported rfc list even longer 2011-03-09 18:41:52 +00:00			`* 403{3,4,5} - DNSSEC + validation functions`
add URI record 2012-02-18 20:49:02 +00:00			`* 4255 - SSHFP record`
Whitespace cleanup 2013-09-20 15:15:27 +00:00			`* 4343 - Case insensitivity`
add URI record 2012-02-18 20:49:02 +00:00			`* 4408 - SPF record`
tweaks 2011-03-22 08:44:33 +00:00			`* 4509 - SHA256 Hash in DS`
Add ref to 4592 and tests it 2012-02-15 09:28:55 +00:00			`* 4592 - Wildcards in the DNS`
more tsig work - still does not validate but getting close 2011-03-14 11:28:04 +00:00			`* 4635 - HMAC SHA TSIG`
blah 2012-02-18 20:25:37 +00:00			`* 4701 - DHCID`
Add id.server and authors.server to ns 2011-07-29 10:24:41 +00:00			`* 4892 - id.server`
Whitespace cleanup 2013-09-20 15:15:27 +00:00			`* 5001 - NSID`
add URI record 2012-02-18 20:49:02 +00:00			`* 5155 - NSEC3 record`
			`* 5205 - HIP record`
update readme 2012-04-18 12:52:49 +00:00			`* 5702 - SHA2 in the DNS`
documentation updates 2011-01-27 08:29:11 +00:00			`* 5936 - AXFR`
Update the readme 2012-05-03 06:59:02 +00:00			`* 6605 - ECDSA`
Add the NID record 2012-11-17 20:26:48 +00:00			`* 6742 - ILNP DNS`
update readme 2013-04-27 15:57:33 +00:00			`* 6891 - EDNS0 update`
Update the readme 2012-05-03 06:59:02 +00:00			`* xxxx - URI record (draft)`
small tweaks to the readme 2012-10-17 07:06:49 +00:00			`* xxxx - EDNS0 DNS Update Lease (draft)`
update readme 2013-04-27 15:57:33 +00:00			`* xxxx - IEU48/IEU64 records (draft)`
Use correct number 2013-05-11 16:04:55 +00:00			`* xxxx - Algorithm-Signal (draft)`
add the remaining flags in the DNS headers Next up: EDNS 2010-12-21 13:41:48 +00:00
docs 2012-08-26 20:32:47 +00:00			`## Loosely based upon`
Bring funkensturm up to date for the new api 2011-02-10 11:26:26 +00:00
			* `ldns`
			* `NSD`
			* `Net::DNS`
			* `GRONG`