fix and relax cabal
[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 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-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) |
163 | [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) |
164
165 ## Author
166
167 Eugene Crosser \<crosser at average dot org\>    
168 <http://www.average.org/~crosser/>