More detailed setup info

README.md

@@ -5,10 +5,11 @@ A Bitcoin DNS Seeder written in Rust.
 ## Usage
 
 ```
-Usage: dnsseedrs [OPTIONS] <SERVER_NAME> <SOA_RNAME>
+Usage: dnsseedrs [OPTIONS] <SEED_DOMAIN> <SERVER_NAME> <SOA_RNAME>
 
 Arguments:
-  <SERVER_NAME>  
+  <SEED_DOMAIN>  The domain name for which this server will return results for
+  <SERVER_NAME>  The domain name of this server itself, i.e. what the NS record will point to
   <SOA_RNAME>    The exact string to place in the rname field of the SOA record
 
 Options:
@@ -24,6 +25,7 @@ Options:
   -a, --address <ADDRESS>          [default: 0.0.0.0]
   -p, --port <PORT>                [default: 53]
       --chain <CHAIN>              [default: main]
+      --dnssec-keys <DNSSEC_KEYS>  The path to a directory containing DNSSEC keys produced by dnssec-keygen
   -h, --help                       Print help
   -V, --version                    Print version
 ```
@@ -115,7 +117,150 @@ minute window will receive the same response.
 
 #### TTL
 
-Returned records use a TTL of 60 seconds.
+A few different TTLs are in use depending on the record type.
+
+* A, AAAA, and NSEC: 60 seconds
+* SOA: 900 seconds
+  * SOA also specify a minimum TTL of 60 seconds
+* NS: 86400 seconds (1 day)
+* DNSKEY: 3600 seconds (1 hour)
+
+#### DNSSEC
+
+The DNS server supports DNSSEC and will automatically respond to DNSSEC requests if DNSSEC keys
+are available.
+
+Use `--dnssec-keys <path>` to provide the path to a directory containing the keypairs.
+Keys are expected to be in the format produced by BIND9's `dnssec-keygen` utility.
+
+The currently supported signing algorithms are:
+* ECDSAP256SHA256
+* ED25519
+
+The implementation of DNSSEC expects 2 keys. One key will have a flag set that indicates that it
+can be used to sign other keys. This key will be used to sign the keys used by this server when it
+sends a DNSKEY record, and it's hash will be signed by your parent DNS Zone's key(s). It is
+referred to as the Key Signing Key (KSK). The other key, referred to as the Zone Signing Key,
+will be used to sign all other records.
+
+When multiple KSKs or ZSKs are present, all will be used to produce signatures over the Resource
+Record set as applicable.
+
+## Installation
+
+DNSSeedrs is a single self contained binary. Simple compile it with `cargo build --release` and
+the resulting `dnsseedrs` binary can be used as a simple server binary.
+
+### Basic Invocation and DNS Setup
+
+Since DNS uses delegation, additional configuration in the parent zone is required, and some of
+this information must also be provided to DNSSeedrs. These are the required arguments of:
+
+* `<SEED_DOMAIN>`: The domain name that will be queried. Querying this domain returns the addresses
+of nodes that can be connected to. DNSSeedrs controls this Zone.
+* `<SERVER_NAME>`: The domain name of this server itself. There must be a NS record in the parent
+Zone which specifies this name as the nameserver for `<SEED_DOMAIN>`
+* `<SOA_RNAME>`: The email address of the server administrator formatted as a domain name. The `@`
+is replaced with a `.`, and all `.`s in the username of the email must be escaped (`\.`).
+
+For example, for a seeder domain of `seeder.example.com`, hosted at `ns.example.com`, adminstered
+by `[email protected]`:
+
+```
+$ dnsseedrs seeder.example.com ns.example.com "john\.doe.example.com"
+```
+
+And there would additionally be the NS record:
+
+```
+seeder.example. IN NS ns.example.com.
+```
+
+### Crawler Seeding
+
+Of course DNSSeedrs is not useful if it does not have any nodes to provide to clients. However,
+it does not have it's own set of seed nodes nor does it query other DNS seeders. Rather it must
+be provided some initial seed nodes to connect to. These will be inserted into the database and
+will subsequently be used to bootstrap the crawler. Seednoes are specified using the `-s` or
+`--seednode` options.
+
+For example, to also use `198.51.100.1:8333`, `[2001:db8::1]:8333`, `e4tyx226c6xj3szkfwybqem6ccxwnfwkxdfjuo52vmnwpittkyeskt7k
+.onion:8333`, and `np3md3om4svfflq6iolnr4hzsrbxug3wjknawc6stho4q4f7if56.b32.i2p:0` as seednodes
+in the previous example:
+
+```
+$ dnsseedrs -s 198.51.100.1:8333 -s [2001:db8::1]:8333 -s e4tyx226c6xj3szkfwybqem6ccxwnfwkxdfjuo52vmnwpittkyeskt7k.onion:9333 -s np3md3om4svfflq6iolnr4hzsrbxug3wjknawc6stho4q4f7if56.b32.i2p:0 seeder.example.com ns.example.com "john\.doe.example.com"
+```
+
+### Anonymity Networks
+
+Since Bitcoin supports the Tor, I2P, and CJDNS anonymity networks, DNSSeedrs does as well in order
+to discover those nodes and present them in the database dumps to be used for fixed seed generation.
+
+### Tor
+
+Tor can be connected via a SOCKS5 proxy. See Tor's documentation to setup the proxy server. Once it
+is available, it can be connected to by setting `--onion-proxy <proxy address>`. The default is
+`127.0.0.1:9050`.
+
+The crawler thread will automatically check to see if this proxy is available and use it if it is.
+This check is only done once at startup. If the proxy goes down while DNSSeedrs is running, this
+will not be detected and will negatively effect the reliability scores of Tor nodes.
+
+### I2P
+
+I2P can be connected via a SOCKS5 proxy. See your I2P router's documentation to setup the proxy
+server. Once it is available, it can be connected to by setting `--i2p-proxy <proxy address>`.
+The default is `127.0.0.1:4447`.
+
+The crawler thread will automatically check to see if this proxy is available and use it if it is.
+This check is only done once at startup. If the proxy goes down while DNSSeedrs is running, this
+will not be detected and will negatively effect the reliability scores of I2P nodes.
+
+### CJDNS
+
+CJDNS creates a tunnel interface that uses a private range of IPv6 addresses. Other than setting it
+up, there is no special configuration required.
+
+### Network Reachability
+
+For IPv4, IPv6, and CJDNS, no reachability tests are automatically done. As such, if these networks
+are not reachable, the crawler will not know and this will negatively impact reliability scores
+for any such nodes.
+
+IPv4 and IPv6 are assumed to be reachable by default. If they are not reachable, set `--no-ipv4`
+and `--no-ipv6` respectively.
+
+CJDNS is assumed to be unreachable by default. It can be enabled by setting `-c` or `--cjdns-reachable`.
+
+### DNSSEC Setup
+
+DNSSEC requires additional setup in order work properly. Specifically, at least one ZSK and one KSK
+must be generated and made available to DNSSeedrs. These keys are in the seeder domain name's Zone,
+so should use the name of `<SEED_DOMAIN>`.
+
+To generate `ECDSAP256SHA256` keys for `seeder.example.com`:
+
+```
+$ dnssec-keygen -a ECDSAP256SHA256 seeder.example.com
+Generating key pair.
+Kseeder.example.com.+013+53945
+$ dnssec-keygen -a ECDSAP256SHA256 -f KSK seeder.example.com
+Generating key pair.
+Kseeder.example.com.+013+20806
+```
+
+`--dnssec-keys <path>` can then be used to point DNSSeedrs to the directory containing the keys.
+DNSSeedrs will also only load the keys that belong to `<SEED DOMAIN>`, as indicated by their
+filenames.
+
+Additionally, a DS record committing to each KSK will need to be added to the parent Zone's DNS.
+This record can be produced with:
+
+```
+$ dnssec-dsfromkey Kseeder.example.com.+013+20806.key
+seeder.example.com. IN DS 20806 13 2 82197169AEEFA02FD911BEABD9356739F7F807C072493A1AEA4B90396EE29074
+```
 
 ## License