README.md

   1 % Namecoin pipe backend for PowerDNS
   2
   3 There exists a project named
   4 [nmcontrol](https://github.com/namecoin/nmcontrol) to create an
   5 all-in-one tool that can, among other things, act as a DNS server
   6 for the `.bit` zone. There is also a tool,
   7 [NamecoinToBind](https://github.com/namecoin/NamecoinToBind),
   8 for offline conversion of namecoin data into BIND zone file.
   9
  10 Unlike those, this project is a single-purpose tool acting as a (real
  11 time) bridge between [Namecoin](http://namecoin.info/) and DNS.
  12 It is implemented as a `pipe backend` to
  13 [PowerDNS](https://www.powerdns.com/), which provides stable DNS
  14 frontend, and has simple backend interface.
  15
  16 ## Building
  17
  18 The program is a single executable to be run by PowerDns's pipe
  19 backend. It is written in [Haskell](http://www.haskell.org/).
  20 If you have haskell installed on your system, run
  21
  22 ```
  23 cabal configure
  24 ```
  25
  26 followed by
  27
  28 ```
  29 cabal build
  30 ```
  31
  32 and hopefully it will tell you what packages are missing. You can
  33 install them either with your OS package manager (if they exist in
  34 your distribution) or with `cabal install`.
  35
  36 ## Installing
  37
  38 In the powerdns configuration, you want to specify `master=yes`.
  39 Enable `pipe` backend by setting `launch=pipe`.
  40 Wherever your pdns package keeps the backend configurations, set
  41 this for the pipe backend:
  42
  43 ```
  44 pipe-command=/path/to/pdns-pipe-nmc
  45 pipe-timeout=10000
  46 pipe-regex=.bit;.*$
  47 pipebackend-abi-version=1 ## all versions supported, but extra data ignored
  48 ```
  49
  50 Copy `pdns-pipe-nmc` to the place that you've set up as `pipe-command`.
  51 Copy your namecoin cofig file to `/etc/namecoin.conf` and make sure it
  52 is readable by the userid specified in the powerdns config. Entries
  53 recognized in the `/etc/namecoin.conf` file (with default values) are:
  54
  55 ```
  56 rpcuser=
  57 rpcpassword=
  58 rpchost=localhost
  59 rpcport=8336
  60 ```
  61
  62 They are the parameters needed to contact the `namecoind` server over
  63 its JsonRPC interface. With default installation on `localhost`, you
  64 will only need to specify `rpcpassword`.
  65
  66 Configure your resolvers to use the PowerDns instance for queries in
  67 the `.bit` zone. This is left as an exercise to the reader.
  68
  69 ## Security Considerations
  70
  71 Namecoin per se has excellent non-repudiation characteristics. But
  72 once you've converted the data into (non-DNSSEC-protected) DNS
  73 format, all bets are off. If you intend to query your powerdns
  74 instance over public Internet, remember that nothing prevents evil
  75 hackers or ruthless governments from tampering with your queries
  76 and powerdns responses. There are two possible approaches to
  77 mitigation of this problem:
  78
  79 * Run namecoind and powerdns as close to the consumer as
  80 possible: on the same host, or at least on the same network, and
  81 keep it guarded.
  82 * I did not try it, but it should be possible to use PowerDNS
  83 [Front-signing](http://doc.powerdns.com/html/dnssec-modes.html#dnssec-frontserver),
  84 so the communication will happen over DNSSEC protocol without the
  85 need to keep the signatures in the zone data itself. You probably
  86 would need to create signing key for the PowerDNS instance, and add
  87 the corresponding public key as "trusted" into the configuration of
  88 your resolvers.
  89
  90 ## Status
  91
  92 Beta. It is mostly feature-complete, but insufficiently tested.
  93 It implements the
  94 [data format specification](http://www.average.org/pdns-pipe-nmc/spec.html)
  95 (SPEC.md in the source distribution) that slightly deviates from the
  96 [official specification](https://wiki.namecoin.info/index.php?title=Domain_Name_Specification).
  97 I am using it to access some of the `.bit` websites and it works
  98 for me.
  99
 100 Try at your risk.
 101
 102 ## Unsolved problems
 103
 104 The biggest problem by far is generating meaningful `SOA` records.
 105
 106 ### SOA Version a.k.a. Generation Count
 107
 108 DNS infrastructure (including PowerDNS implementation) relies on the
 109 "generation" field of the `SOA` RR when it makes decision to invalidate
 110 the cache. So, if there is zone data in the DNS cache, and a DNS server
 111 needs to respond to a request about an object from that zone, it first
 112 checks if the TTL has expired. If it has not, the server takes the data
 113 from the cache. If it has expired, the server asks the "authoritative
 114 source" (which is in our case the dnamecoin daemon) for the SOA record
 115 and compares the generation count in the received response with the
 116 number kept in the cache. If the "authoritative" SOA does not have a
 117 greater generation count than the cached SOA, DNS server **does not**
 118 refresh its cache, presuming that the data there is still valid.
 119
 120 So, it is important that the generation count in the SOA record is
 121 incremented every time when the domain object, or any of the object that
 122 it "include"-s or to which it "delegate"-s is changed.
 123
 124 At present, there is no machanism for that. In most cases, simply
 125 summing the number of entries in `name_history`-s of all domain object
 126 involved in resolution would work, but this approach would produce
 127 wrong result when an "import" entry is removed from a domain, because
 128 in such case the sum would decrease. It would also not notice the
 129 changes in an object "include"-ed in a subdomain, unless complete
 130 recursive resolution of the subdomain tree is enforced for when
 131 SOA record is requested. That would invalidate the reason to have
 132 caching in the first place.
 133
 134 One possible workaround, currently implemented in `pdns-pipe-nmc`, is to
 135 use a derivative of absolute time, in our case the number of 10-munute
 136 intervals elapsed since Namecoin was concieved, as the SOA generation
 137 count.
 138
 139 ### Nameserver field
 140
 141 There is no "reasonable" value that could be placed there. Except
 142 possibly the name of the host on which the PoweDNS instance is running,
 143 in the `.bit` zone. Currently, `pdns-pipe-nmc` just puts a dot "."
 144 there, and no problems where noticed so far.
 145
 146 ## Getting the Software
 147
 148 Check the [project homepage](http://www.average.org/pdns-pipe-nmc/).
 149
 150 ### Source
 151
 152 Git [clone](git://git.average.org/git/pdns-pipe-nmc.git) or
 153 [browse](http://www.average.org/gitweb/?p=pdns-pipe-nmc.git;a=summary),
 154 or use [github mirror](https://github.com/crosser/pdns-pipe-nmc).
 155
 156 ### Binary Executable
 157
 158 There is a binary built for x86_64 Linux with glibc6:
 159
 160 | Executable file                                                                                                      | PGP                                                                 |
 161 |----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
 162 | [**pdns-pipe-nmc.linux-glibc6.x86_64.2014-06-05.git-0.9.0.1**](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-06-05.git-0.9.0.1) | [sig](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-06-05.git-0.9.0.1.sig) |
 163 | [pdns-pipe-nmc.linux-glibc6.x86_64.2014-05-01.git-0.9.0.0](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-05-01.git-0.9.0.0) | [sig](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-05-01.git-0.9.0.0.sig) |
 164 | [pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-22.git-108b6c2](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-22.git-108b6c2) | [sig](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-22.git-108b6c2.sig) |
 165 | [pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f) | [sig](http://www.average.org/pdns-pipe-nmc/pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f.sig) |
 166
 167 ## Author
 168
 169 Eugene Crosser \<crosser at average dot org\>
 170 <http://www.average.org/~crosser/>