document problem with SOA version
[pdns-pipe-nmc.git] / 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 built as a single executable to be run by PowerDns's
19 pipe backend. It is written in [Haskell](http://www.haskell.org/).
20 There is no `cabal` configuration at the moment, so to build it,
21 simply run
22
23 ```
24 ghc --make pdns-pipe-nmc
25 ```
26
27 and install any missing packages it complains about.
28
29 ## Installing
30
31 In the powerdns configuration, you want to specify `master=yes`.
32 Enable `pipe` backend by setting `launch=pipe`.
33 Wherever your pdns package keeps the backend configurations, set
34 this for the pipe backend:
35
36 ```
37 pipe-command=/path/to/pdns-pipe-nmc
38 pipe-timeout=10000
39 pipe-regex=.bit;.*$
40 pipebackend-abi-version=1 ## all versions supported, but extra data ignored
41 ```
42
43 Copy `pdns-pipe-nmc` to the place that you've set up as `pipe-command`.
44 Copy your namecoin cofig file to `/etc/namecoin.conf` and make sure it
45 is readable by the userid specified in the powerdns config. Entries
46 recognized in the `/etc/namecoin.conf` file (with default values) are:
47
48 ```
49 rpcuser=
50 rpcpassword=
51 rpchost=localhost
52 rpcport=8336
53 ```
54
55 They are the parameters needed to contact the `namecoind` server over
56 its JsonRPC interface. With default installation on `localhost`, you
57 will only need to specify `rpcpassword`.
58
59 Configure your resolvers to use the PowerDns instance for queries in
60 the `.bit` zone. This is left as an exercise to the reader.
61
62 ## Security Considerations
63
64 Namecoin per se has excellent non-repudiation characteristics. But
65 once you've converted the data into (non-DNSSEC-protected) DNS
66 format, all bets are off. If you intend to query your powerdns
67 instance over public Internet, remember that nothing prevents evil
68 hackers or ruthless governments from tampering with your queries
69 and powerdns responses. There are two possible approaches to
70 mitigation of this problem:
71
72 * Run namecoind and powerdns as close to the consumer as
73 possible: on the same host, or at least on the same network, and
74 keep it guarded.
75 * I did not try it, but it should be possible to use PowerDNS
76 [Front-signing](http://doc.powerdns.com/html/dnssec-modes.html#dnssec-frontserver),
77 so the communication will happen over DNSSEC protocol without the
78 need to keep the signatures in the zone data itself. You probably
79 would need to create signing key for the PowerDNS instance, and add
80 the corresponding public key as "trusted" into the configuration of
81 your resolvers.
82
83 ## Status
84
85 Alpha. It is insufficiently tested, and there are loose ends in the
86 functionality. For example, version in the `SOA` record is bogus.
87 Some of the the problems are due to incomplete and/or imprecise
88 [definition of the domain data format](https://wiki.namecoin.info/index.php?title=Domain_Name_Specification)
89 on the wiki. That said, I am using it to access some of the `.bit` websites
90 and did not notice anomalies so far.
91
92 Try at your risk.
93
94 ## Unsolved problems
95
96 The biggest problem by far is generating meaningful `SOA` records. DNS
97 infrastructure (including PowerDNS implementation) relies on the "generation"
98 field of the `SOA` RR when it makes decision to invalidate the cache. So,
99 if there is zone data in the DNS cache, and a DNS server needs to respond
100 to a request about an object from that zone, it first checks if the TTL
101 has expired. If it has not, the server takes the data from the cache. If
102 it has expired, the server asks the "authoritative source" (which is in
103 our case the dnamecoin daemon) for the SOA record and compares the
104 generation count in the received response with the number kept in the
105 cache. If the "authoritative" SOA does not have a greater generation
106 count than the cached SOA, DNS server **does not** refresh its cache,
107 presuming that the data there is still valid.
108
109 So, it is important that the generation count in the SOA record is
110 incremented every time when the domain object, or any of the object that
111 it "include"-s or to which it "delegate"-s is changed.
112
113 At present, there is no machanism for that. In most cases, simply
114 summing the number of entries in `name_history`-s of all domain object
115 involved in resolution would work, but this approach would produce
116 wrong result when an "import" entry is removed from a domain, because
117 in such case the sum would decrease. It would also not notice the
118 changes in an object "include"-ed in a subdomain, unless complete
119 recursive resolution of the subdomain tree is enforced for when
120 SOA record is requested. That would invalidate the reason to have
121 caching in the first place.
122
123 One possible workaround would be to use some derivative of absolute
124 time, such as the number of hours elapsed since the epoch, for the
125 SOA generation count.
126
127 At the time of this writing, `pdns-pipe-nmc` simply reports zero as
128 the SOA generation count. This leads to stale results until `pdnsd`
129 is restarted.
130
131 ## Getting the Software
132
133 Check the [project homepage](http://www.average.org/pdns-pipe-nmc/).
134
135 ### Source
136
137 Git [clone](git://git.average.org/git/pdns-pipe-nmc.git) or
138 [browse](http://www.average.org/gitweb/?p=pdns-pipe-nmc.git;a=summary),
139 or use [github mirror](https://github.com/crosser/pdns-pipe-nmc).
140
141 ### Binary Executable
142
143 There is a binary built for x86_64 Linux with glibc6:
144
145 | Executable file                                                                                                      | PGP                                                                 |
146 |----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
147 | [pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f](pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f) | [sig](pdns-pipe-nmc.linux-glibc6.x86_64.2014-04-20.git-e9bd43f.sig) |
148
149 ## Author
150
151 Eugene Crosser \<crosser at average dot org\>    
152 <http://www.average.org/~crosser/>