docs: explain dnsaddr suffix matching

includes - dnsaddr suffix matching - caveat about max udp dns response size see: #102 License: MIT Signed-off-by: Oli Evans <[email protected]>
multiformats · Nov 12, 2019 · 7808a71 · 7808a71
1 parent 91c32b6
commit 7808a71
Showing 1 changed file with 49 additions and 0 deletions.
diff --git a/protocols/DNSADDR.md b/protocols/DNSADDR.md
@@ -36,3 +36,52 @@ So, `/dnsaddr/bootstrap.libp2p.io` resolves to (at least) four multiaddrs:
 /ip4/147.75.83.83/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb
 /ip6/2604:1380:2000:7a00::1/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb
 ```
+
+## Suffix matching
+
+A `/dnsaddr` may specify additional nested protocols that must match when resolving the txt record. When the TXT records are resolved, items whose suffix doesn't match the provided one are dropped.
+
+The [default IPFS bootstrap list](https://github.com/ipfs/go-ipfs-config/blob/ed60afb72517463df516d7d6ea0a98fc07369024/bootstrap_peers.go#L22) contains 4 dnsaddrs for the domain `bootstrap.libp2p.io`, and each one specifies has a different Peer ID. The first one is:
+
+```go
+"/dnsaddr/bootstrap.libp2p.io/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
+```
+
+To resolve that multiaddr first look up the txt records at `_dnsaddr.bootstrap.libp2p.io`
+
+```console
+$ dig +short txt _dnsaddr.bootstrap.libp2p.io
+"dnsaddr=/dnsaddr/ams-2.bootstrap.libp2p.io/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb"
+"dnsaddr=/dnsaddr/sjc-1.bootstrap.libp2p.io/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN"
+"dnsaddr=/dnsaddr/nrt-1.bootstrap.libp2p.io/tcp/4001/ipfs/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt"
+"dnsaddr=/dnsaddr/ewr-1.bootstrap.libp2p.io/tcp/4001/ipfs/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa"
+```
+
+check each record to find ones where the suffix matches the one specified on the multiaddr: `/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN` which leaves us with just:
+
+```
+/dnsaddr/sjc-1.bootstrap.libp2p.io/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN
+```
+
+In this case, it's another `/dnsaddr`, so take the same steps again, this time with the `_dnsaddr.sjc-1.bootstrap.libp2p.io` domain:
+
+```console
+$ dig +short txt _dnsaddr.sjc-1.bootstrap.libp2p.io
+"dnsaddr=/ip4/147.75.69.143/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN"
+"dnsaddr=/ip6/2604:1380:1000:6000::1/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN"
+```
+
+Now both records match the provided suffix of `/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN`, so our multiaddr finally resolves to:
+
+```
+/ip4/147.75.69.143/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN
+/ip6/2604:1380:1000:6000::1/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN
+```
+
+## Caveats
+
+Some implementations may fail to resolve `/dnsaddr` addresses if the total size of all your published TXT records for a given domain exceed 512 bytes, as the initial dns response will be truncated to 512 bytes.
+
+See: https://serverfault.com/questions/840241/do-dns-queries-always-travel-over-udp
+
+For the default IPFS bootstrap list, we use recursive `/dnsaddr` resolution, as described above, so we only publish 4 txt records on the primary domain `bootstrap.libp2p.io`, which in turn resolve to a pair of `ip6` and `ip4` multiaddrs per bootstrap node. In that way the dns response at both steps fits within 512 bytes.