From 91c32b64f151f83b0553e747aabf5584f486c8fa Mon Sep 17 00:00:00 2001 From: Alan Shaw Date: Mon, 11 Nov 2019 18:20:18 +0000 Subject: [PATCH] docs: add dnsaddr protocol spec (#102) * docs: add dnsaddr protocol spec ...to the best of my knowledge. Added as separate doc in `protocols` dir so existing link in README becomes not 404 :) * fix: clarify address being queried * fix: better syntax highlighting on gh * Update protocols/DNSADDR.md Co-Authored-By: Marcin Rataj --- README.md | 2 +- protocols/DNSADDR.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 protocols/DNSADDR.md diff --git a/README.md b/README.md index 00b0343..8f67a5d 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ TODO: most of these are way underspecified - /ip4, /ip6 - /dns4, /dns6 -- /dnsaddr +- [/dnsaddr](protocols/DNSADDR.md) - /tcp - /udp - /utp diff --git a/protocols/DNSADDR.md b/protocols/DNSADDR.md new file mode 100644 index 0000000..62275ab --- /dev/null +++ b/protocols/DNSADDR.md @@ -0,0 +1,38 @@ +# `dnsaddr` + +`dnsaddr` is a protocol that instructs the resolver to lookup multiaddr(s) in DNS TXT records for the domain name in it's value section. + +To resolve a `dnsaddr` multiaddr, the domain name in the value section must first be prefixed with `_dnsaddr.`. Then a DNS query to lookup TXT records for the domain must be made. There may be multiple DNS TXT records for the domain. Valid `dnsaddr` TXT records begin with `dnsaddr=`, followed by a single multiaddr. Recursive lookups are allowed. + +## Example + +`/dnsaddr/bootstrap.libp2p.io` would result in a DNS TXT record query for `_dnsaddr.bootstrap.libp2p.io`. + +```sh +# TXT records for `_dnsaddr.bootstrap.libp2p.io`: +dnsaddr=/dnsaddr/sjc-1.bootstrap.libp2p.io/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN +dnsaddr=/dnsaddr/ams-2.bootstrap.libp2p.io/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb +# ... +``` + +...which further resolve to: + +```sh +# TXT records for `_dnsaddr.sjc-1.bootstrap.libp2p.io`: +dnsaddr=/ip6/2604:1380:1000:6000::1/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN +dnsaddr=/ip4/147.75.69.143/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN + +# TXT records for `_dnsaddr.ams-2.bootstrap.libp2p.io`: +dnsaddr=/ip4/147.75.83.83/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb +dnsaddr=/ip6/2604:1380:2000:7a00::1/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb +``` + +So, `/dnsaddr/bootstrap.libp2p.io` resolves to (at least) four multiaddrs: + +``` +/ip6/2604:1380:1000:6000::1/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN +/ip4/147.75.69.143/tcp/4001/ipfs/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN + +/ip4/147.75.83.83/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb +/ip6/2604:1380:2000:7a00::1/tcp/4001/ipfs/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb +```