From a4626efdb2174be17897f47c6494fee7ed7a8710 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Mon, 23 Jul 2018 15:01:55 +1200 Subject: [PATCH 01/14] feat: initial description of peer discovery with MDNS --- discovery/mdns.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 discovery/mdns.md diff --git a/discovery/mdns.md b/discovery/mdns.md new file mode 100644 index 000000000..5a2205560 --- /dev/null +++ b/discovery/mdns.md @@ -0,0 +1,94 @@ +# Multicast DNS +Author: Richard Schneider (makaretu@gmail.com) + + +## Overview + +The goal is to allow peers to discover each other when on the same local network with zero configuration. +MDNS uses a multicast system of DNS records; this allows all peers on the local network to see all query responses. + +Conceptually, it is very simple. When a peer starts (or detects a network change), it sends a query for all peers. +As responses come in, the peer adds the other peers information into is local database of peers. + +## Definitions + +`service-name` is the DNS-SD service name for all IPFS peers. It is defined as `_ipfs._udp.local`. + +`host-name` is the name of the peer. It derived from the peer's ID and `ipfs.local`, for example +`Qmid.ipfs.local`. + +`peer-id` is the ID of the peer. It normally is the base-58 enconding of the hash of the peer's public key. + +`port` is the port that the peer listens on. Normally 4001. + +## Peer Discovery + +### Request + +To find all peers, a DNS message is sent with the question `_ipfs._udp.local PTR`. +Peers will then start responding with their details. + +Note that a peer must respond to it's own query. Thus allows other peers to passively discover it. + +### Response + +On receipt of a `find all peers` query, a peer sends a DNS response message (QR = 1) that contains +the **answer** + + PTR . + +The **additional records** of the response contains the peer's discovery details + + . SRV ... + . TXT ... + A + AAAA + + +Multiple A and AAAA records are expected. The `TXT` is not needed for IPFS peer discovery, but is required by DNS-SD. + +#### Multiported Peers + +If a peer is listening on multiple ports, it must respond with multiple `SRV` records for each +port is listening on. If the ports do not listen on the same IP addresses, then each 'SRV' record +must have a different `host-name`. + +#### Multiaddress + +**TODO** from DNS records + +**TODO** to DNS records + +## DNS Service Discovery + +DNS-SD support is not needed for IPFS peers to discover each other. However, it is +extremely usefull for network admistrators to discover what is running on the +network. + +### Meta Query + +This allows discovery of all services. The question is `_services._dns-sd._udp.local PTR`. + +A peer responds with the answer + + _services._dns-sd._udp.local PTR + +### Gotchas + +Many existing tools ignore the Additional Records and always send individual queries for the +peer's discovery details. To accomodate this, a peer should respond to the following queries: + +- `. SRV` +- `. TXT` +- ` A` +- ` AAAA` + +## References + +- [RFC 1035 - Domain Names (DNS)](https://tools.ietf.org/html/rfc1035) +- [RFC 6762 - Multicast DNS](https://tools.ietf.org/html/rfc6762) +- [RFC 6763 - DNS-Based Service Discovery](https://tools.ietf.org/html/rfc6763) + +## Worked Example + +**TODO** From 9e0e1f556c0a3cec4627397846ff8610944f77d7 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Mon, 23 Jul 2018 20:15:03 +1200 Subject: [PATCH 02/14] fix: grammar --- discovery/mdns.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 5a2205560..f1ebe0214 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -14,12 +14,12 @@ As responses come in, the peer adds the other peers information into is local da `service-name` is the DNS-SD service name for all IPFS peers. It is defined as `_ipfs._udp.local`. -`host-name` is the name of the peer. It derived from the peer's ID and `ipfs.local`, for example +`host-name` is the name of the peer. It is derived from the peer's ID and `ipfs.local`, for example `Qmid.ipfs.local`. `peer-id` is the ID of the peer. It normally is the base-58 enconding of the hash of the peer's public key. -`port` is the port that the peer listens on. Normally 4001. +`port` is a port that the peer listens on. Normally 4001. ## Peer Discovery @@ -37,7 +37,7 @@ the **answer** PTR . -The **additional records** of the response contains the peer's discovery details +The **additional records** of the response contain the peer's discovery details . SRV ... . TXT ... @@ -50,7 +50,7 @@ Multiple A and AAAA records are expected. The `TXT` is not needed for IPFS peer #### Multiported Peers If a peer is listening on multiple ports, it must respond with multiple `SRV` records for each -port is listening on. If the ports do not listen on the same IP addresses, then each 'SRV' record +port it is listening on. If the ports do not listen on the same IP addresses, then each 'SRV' record must have a different `host-name`. #### Multiaddress From 154424ffad966ffd484d01ac2c2101d6c773b277 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Mon, 23 Jul 2018 20:24:15 +1200 Subject: [PATCH 03/14] fix: typos --- discovery/mdns.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index f1ebe0214..5442023c8 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -35,14 +35,14 @@ Note that a peer must respond to it's own query. Thus allows other peers to pas On receipt of a `find all peers` query, a peer sends a DNS response message (QR = 1) that contains the **answer** - PTR . + PTR . The **additional records** of the response contain the peer's discovery details - . SRV ... - . TXT ... - A - AAAA + . SRV ... + . TXT ... + A + AAAA Multiple A and AAAA records are expected. The `TXT` is not needed for IPFS peer discovery, but is required by DNS-SD. @@ -78,8 +78,8 @@ A peer responds with the answer Many existing tools ignore the Additional Records and always send individual queries for the peer's discovery details. To accomodate this, a peer should respond to the following queries: -- `. SRV` -- `. TXT` +- `. SRV` +- `. TXT` - ` A` - ` AAAA` From b2c450e19dd4110e7dd9984f85d181862287c678 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Wed, 25 Jul 2018 12:04:14 +1200 Subject: [PATCH 04/14] docs: multiaddress --- discovery/mdns.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 5442023c8..51185bb80 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -55,9 +55,17 @@ must have a different `host-name`. #### Multiaddress -**TODO** from DNS records +For this spec, a multiaddress has the form `///tcp//ipfs/`. A multiaddress is +generated from the various Additional Records. + +`peer-id` is the first label of the SRV name + +`port` is the the SRV port + +`ip` is "ip4" for an A record or "ip6" for an AAAA record. + +`addr` is the ip4/ip6 address from the A/AAAA record. -**TODO** to DNS records ## DNS Service Discovery From 105fd2b70481484bb860846a8078e9f599556454 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Fri, 27 Jul 2018 12:01:30 +1200 Subject: [PATCH 05/14] fix: '_ipfs' => '_p2p' --- discovery/mdns.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 51185bb80..5bd0e28ba 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -12,10 +12,10 @@ As responses come in, the peer adds the other peers information into is local da ## Definitions -`service-name` is the DNS-SD service name for all IPFS peers. It is defined as `_ipfs._udp.local`. +`service-name` is the DNS-SD service name for all peers. It is defined as `_p2p._udp.local`. -`host-name` is the name of the peer. It is derived from the peer's ID and `ipfs.local`, for example -`Qmid.ipfs.local`. +`host-name` is the name of the peer. It is derived from the peer's ID and `p2p.local`, for example +`Qmid.p2p.local`. `peer-id` is the ID of the peer. It normally is the base-58 enconding of the hash of the peer's public key. @@ -25,7 +25,7 @@ As responses come in, the peer adds the other peers information into is local da ### Request -To find all peers, a DNS message is sent with the question `_ipfs._udp.local PTR`. +To find all peers, a DNS message is sent with the question `_p2p._udp.local PTR`. Peers will then start responding with their details. Note that a peer must respond to it's own query. Thus allows other peers to passively discover it. From a9c587cc0b3f1d6d340385a77db32e4d3a472156 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Fri, 27 Jul 2018 12:30:46 +1200 Subject: [PATCH 06/14] fix: use TXT dnsaddr for multi address --- discovery/mdns.md | 48 +++++++++++++++++++---------------------------- 1 file changed, 19 insertions(+), 29 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 5bd0e28ba..93eddbf6c 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -39,38 +39,16 @@ the **answer** The **additional records** of the response contain the peer's discovery details - . SRV ... - . TXT ... - A - AAAA - - -Multiple A and AAAA records are expected. The `TXT` is not needed for IPFS peer discovery, but is required by DNS-SD. - -#### Multiported Peers - -If a peer is listening on multiple ports, it must respond with multiple `SRV` records for each -port it is listening on. If the ports do not listen on the same IP addresses, then each 'SRV' record -must have a different `host-name`. - -#### Multiaddress - -For this spec, a multiaddress has the form `///tcp//ipfs/`. A multiaddress is -generated from the various Additional Records. - -`peer-id` is the first label of the SRV name - -`port` is the the SRV port - -`ip` is "ip4" for an A record or "ip6" for an AAAA record. - -`addr` is the ip4/ip6 address from the A/AAAA record. - + . TXT "dnsaddr=..." + +The TXT record contains the multiaddresses that the peer is listening on. Each multiaddress +is a TXT attribute with the form `dnsaddr=/ip4/.../tcp/.../p2p/QmId`. Multiple `dnsaddr` attributes +are expected. ## DNS Service Discovery -DNS-SD support is not needed for IPFS peers to discover each other. However, it is -extremely usefull for network admistrators to discover what is running on the +DNS-SD support is not needed for peers to discover each other. However, it is +extremely usefull for network administrators to discover what is running on the network. ### Meta Query @@ -81,6 +59,17 @@ A peer responds with the answer _services._dns-sd._udp.local PTR +### Find All Response + +On receipt of a `find all peers` query, the following **additional records** should be included + + . SRV ... + A + AAAA + +If a peer is listening on multiple ports, it should respond with multiple `SRV` records for each +port it is listening on. + ### Gotchas Many existing tools ignore the Additional Records and always send individual queries for the @@ -96,6 +85,7 @@ peer's discovery details. To accomodate this, a peer should respond to the follo - [RFC 1035 - Domain Names (DNS)](https://tools.ietf.org/html/rfc1035) - [RFC 6762 - Multicast DNS](https://tools.ietf.org/html/rfc6762) - [RFC 6763 - DNS-Based Service Discovery](https://tools.ietf.org/html/rfc6763) +- [Multiaddr](https://github.com/multiformats/multiaddr) ## Worked Example From 2e0219a819daa9d6fa73329aaa23ded633f70575 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Fri, 27 Jul 2018 14:57:40 +1200 Subject: [PATCH 07/14] feat: open issues --- discovery/mdns.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/discovery/mdns.md b/discovery/mdns.md index 93eddbf6c..8257bf969 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -80,6 +80,12 @@ peer's discovery details. To accomodate this, a peer should respond to the follo - ` A` - ` AAAA` +## Issues + +- like urls, dns names are case insensitive. A `peer-id` is base58btc encoded and is case sensitive. +- MDNS requires link local addresses. Loopback and "nat busting" addresses should not sent and must + be ignored on receipt? + ## References - [RFC 1035 - Domain Names (DNS)](https://tools.ietf.org/html/rfc1035) From 8cc12972d21f17c7bf75920e0c98b5d91b294a6d Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Thu, 13 Sep 2018 12:44:19 +1200 Subject: [PATCH 08/14] fix: names are case insensitive --- discovery/mdns.md | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 8257bf969..3c19baa32 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -14,12 +14,11 @@ As responses come in, the peer adds the other peers information into is local da `service-name` is the DNS-SD service name for all peers. It is defined as `_p2p._udp.local`. -`host-name` is the name of the peer. It is derived from the peer's ID and `p2p.local`, for example -`Qmid.p2p.local`. +`host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. -`peer-id` is the ID of the peer. It normally is the base-58 enconding of the hash of the peer's public key. +`peer-name` is the case-insenstive ID of the peer and less than 64 characters. It is normally is the base-32 encoding of peer's ID. -`port` is a port that the peer listens on. Normally 4001. +Note that all names are case insensitive. ## Peer Discovery @@ -28,22 +27,22 @@ As responses come in, the peer adds the other peers information into is local da To find all peers, a DNS message is sent with the question `_p2p._udp.local PTR`. Peers will then start responding with their details. -Note that a peer must respond to it's own query. Thus allows other peers to passively discover it. +Note that a peer must respond to it's own query. This allows other peers to passively discover it. ### Response On receipt of a `find all peers` query, a peer sends a DNS response message (QR = 1) that contains the **answer** - PTR . + PTR . The **additional records** of the response contain the peer's discovery details - . TXT "dnsaddr=..." + . TXT "dnsaddr=..." The TXT record contains the multiaddresses that the peer is listening on. Each multiaddress -is a TXT attribute with the form `dnsaddr=/ip4/.../tcp/.../p2p/QmId`. Multiple `dnsaddr` attributes -are expected. +is a TXT attribute with the form `dnsaddr=.../p2p/QmId`. Multiple `dnsaddr` attributes +and/or TXT records are allowed. ## DNS Service Discovery @@ -63,26 +62,22 @@ A peer responds with the answer On receipt of a `find all peers` query, the following **additional records** should be included - . SRV ... + . SRV ... A AAAA -If a peer is listening on multiple ports, it should respond with multiple `SRV` records for each -port it is listening on. - ### Gotchas Many existing tools ignore the Additional Records and always send individual queries for the peer's discovery details. To accomodate this, a peer should respond to the following queries: -- `. SRV` -- `. TXT` +- `. SRV` +- `. TXT` - ` A` - ` AAAA` ## Issues -- like urls, dns names are case insensitive. A `peer-id` is base58btc encoded and is case sensitive. - MDNS requires link local addresses. Loopback and "nat busting" addresses should not sent and must be ignored on receipt? From 53d9fafa119c6c425dbf168bf49e9e4ccce4fb23 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Thu, 11 Oct 2018 13:06:19 +1300 Subject: [PATCH 09/14] doc: long peer names --- discovery/mdns.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 3c19baa32..8ad23c813 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -16,9 +16,11 @@ As responses come in, the peer adds the other peers information into is local da `host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. -`peer-name` is the case-insenstive ID of the peer and less than 64 characters. It is normally is the base-32 encoding of peer's ID. +`peer-name` is the case-insenstive unique identifier of the peer and less than 64 characters. +It is normally the base-32 encoding of peer's ID. -Note that all names are case insensitive. +If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) +workaround can be used. ## Peer Discovery From 409c0192eef2c43c1f193db42ae770e1aee63fbb Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Thu, 11 Oct 2018 13:26:46 +1300 Subject: [PATCH 10/14] docs: link to discovery/mdns.md --- 4-architecture.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/4-architecture.md b/4-architecture.md index 3d5344924..daf87ae16 100644 --- a/4-architecture.md +++ b/4-architecture.md @@ -91,7 +91,9 @@ Follows [IPRS spec](/IPRS.md). ### 4.4.1 mDNS-discovery -mDNS-discovery is a Discovery Protocol that uses [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) over local area networks. It emits mDNS beacons to find if there are more peers available. Local area network peers are very useful to peer-to-peer protocols, because of their low latency links. +mDNS-discovery is a Discovery Protocol that uses [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) over local area networks with zero configuration. Local area network peers are very useful to peer-to-peer protocols, because of their low latency links. + +The [mDNS-discovery](discovery/mdns.md) specification describes how to use mDNS to discover other peers. mDNS-discovery is a standalone protocol and does not depend on any other `libp2p` protocol. mDNS-discovery can yield peers available in the local area network, without relying on other infrastructure. This is particularly useful in intranets, networks disconnected from the Internet backbone, and networks which temporarily lose links. From 59e079355c56b772aa7cf6345df796281422d101 Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Thu, 11 Oct 2018 14:36:51 +1300 Subject: [PATCH 11/14] docs: worked example --- discovery/mdns.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 8ad23c813..385faf951 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -92,4 +92,36 @@ peer's discovery details. To accomodate this, a peer should respond to the follo ## Worked Example -**TODO** +Asumming that `peer-id` is `QmQusTXc1Z9C1mzxsqC9ZTFXCgSkpBRGgW4Jk2QYHxKE22`. Then the `peer-name` is `ciqcmoputolsfsigvm7nx5fwkko2eq26h46qhbj6o4co7uyn2f2srdy`. + +To make the examples more readable `id` and `name` are used. + + +### Meta Query + +Find all services on the local network. + +#### Question + +`_services._dns-sd._udp.local PTR` + +#### Answer + +_services._dns-sd._udp.local IN PTR _p2p._udp.local + +### Find All Peers + +Find all peers on the local network + +#### Question + +_p2p._udp.local PTR + +#### Answer + +_p2p._udp.local IN PTR `name`._p2p._udp.local + +#### Additional Records + +- `name`._p2p._udp.local IN TXT dnsaddr=/ip6/fe80::7573:b0a8:46b0:bfea/tcp/4001/ipfs/`id` +- `name`._p2p._udp.local IN TXT dnsaddr=/ip4/192.168.178.21/tcp/4001/ipfs/'id' From 2f3e55d391338a32a7cb67e4e4aa7b78d02e0d8c Mon Sep 17 00:00:00 2001 From: David Dias Date: Fri, 12 Oct 2018 11:52:39 +0100 Subject: [PATCH 12/14] docs: few edits to the structure --- discovery/mdns.md | 56 ++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index 385faf951..b9684a673 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -1,33 +1,28 @@ # Multicast DNS -Author: Richard Schneider (makaretu@gmail.com) +Author: Richard Schneider (makaretu@gmail.com) ## Overview -The goal is to allow peers to discover each other when on the same local network with zero configuration. -MDNS uses a multicast system of DNS records; this allows all peers on the local network to see all query responses. +The goal is to allow peers to discover each other when on the same local network with zero configuration. MDNS uses a multicast system of DNS records; this allows all peers on the local network to see all query responses. -Conceptually, it is very simple. When a peer starts (or detects a network change), it sends a query for all peers. -As responses come in, the peer adds the other peers information into is local database of peers. +Conceptually, it is very simple. When a peer starts (or detects a network change), it sends a query for all peers. As responses come in, the peer adds the other peers information into is local database of peers. ## Definitions -`service-name` is the DNS-SD service name for all peers. It is defined as `_p2p._udp.local`. - -`host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. +- `service-name` is the DNS-SD service name for all peers. It is defined as `_p2p._udp.local`. +- `host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. +- `peer-name` is the case-insenstive unique identifier of the peer and less than 64 characters. -`peer-name` is the case-insenstive unique identifier of the peer and less than 64 characters. It is normally the base-32 encoding of peer's ID. -If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) -workaround can be used. +If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) workaround can be used. ## Peer Discovery ### Request -To find all peers, a DNS message is sent with the question `_p2p._udp.local PTR`. -Peers will then start responding with their details. +To find all peers, a DNS message is sent with the question `_p2p._udp.local PTR`. Peers will then start responding with their details. Note that a peer must respond to it's own query. This allows other peers to passively discover it. @@ -36,21 +31,21 @@ Note that a peer must respond to it's own query. This allows other peers to pas On receipt of a `find all peers` query, a peer sends a DNS response message (QR = 1) that contains the **answer** - PTR . - +``` + PTR . +``` + The **additional records** of the response contain the peer's discovery details - . TXT "dnsaddr=..." - -The TXT record contains the multiaddresses that the peer is listening on. Each multiaddress -is a TXT attribute with the form `dnsaddr=.../p2p/QmId`. Multiple `dnsaddr` attributes -and/or TXT records are allowed. +``` +. TXT "dnsaddr=..." +``` + +The TXT record contains the multiaddresses that the peer is listening on. Each multiaddress is a TXT attribute with the form `dnsaddr=.../p2p/QmId`. Multiple `dnsaddr` attributes and/or TXT records are allowed. ## DNS Service Discovery -DNS-SD support is not needed for peers to discover each other. However, it is -extremely usefull for network administrators to discover what is running on the -network. +DNS-SD support is not needed for peers to discover each other. However, it is extremely usefull for network administrators to discover what is running on the network. ### Meta Query @@ -58,20 +53,23 @@ This allows discovery of all services. The question is `_services._dns-sd._udp. A peer responds with the answer +``` _services._dns-sd._udp.local PTR - +``` + ### Find All Response On receipt of a `find all peers` query, the following **additional records** should be included +``` . SRV ... A AAAA - +``` + ### Gotchas -Many existing tools ignore the Additional Records and always send individual queries for the -peer's discovery details. To accomodate this, a peer should respond to the following queries: +Many existing tools ignore the Additional Records and always send individual queries for the peer's discovery details. To accomodate this, a peer should respond to the following queries: - `. SRV` - `. TXT` @@ -80,8 +78,7 @@ peer's discovery details. To accomodate this, a peer should respond to the follo ## Issues -- MDNS requires link local addresses. Loopback and "nat busting" addresses should not sent and must - be ignored on receipt? +MDNS requires link local addresses. Loopback and "nat busting" addresses should not sent and must be ignored on receipt? ## References @@ -96,7 +93,6 @@ Asumming that `peer-id` is `QmQusTXc1Z9C1mzxsqC9ZTFXCgSkpBRGgW4Jk2QYHxKE22`. Th To make the examples more readable `id` and `name` are used. - ### Meta Query Find all services on the local network. From 479f07c44ac2229592f7ca6a5edb3729ec019f92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Wed, 24 Apr 2019 12:11:30 +0100 Subject: [PATCH 13/14] editorial refinements. --- discovery/mdns.md | 54 +++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index b9684a673..da4e7943f 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -1,55 +1,51 @@ -# Multicast DNS +# Multicast DNS (mDNS) Author: Richard Schneider (makaretu@gmail.com) ## Overview -The goal is to allow peers to discover each other when on the same local network with zero configuration. MDNS uses a multicast system of DNS records; this allows all peers on the local network to see all query responses. +The goal is to allow peers to discover each other when on the same local network with zero configuration. mDNS uses a multicast system of DNS records; this allows all peers on the local network to see all query responses. -Conceptually, it is very simple. When a peer starts (or detects a network change), it sends a query for all peers. As responses come in, the peer adds the other peers information into is local database of peers. +Conceptually, it is very simple. When a peer starts (or detects a network change), it sends a query for all peers. As responses come in, the peer adds the other peers' information into its local database of peers. ## Definitions -- `service-name` is the DNS-SD service name for all peers. It is defined as `_p2p._udp.local`. -- `host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. -- `peer-name` is the case-insenstive unique identifier of the peer and less than 64 characters. - -It is normally the base-32 encoding of peer's ID. - -If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) workaround can be used. +- `service-name` is the DNS Service Discovery (DNS-SD) service name for all peers. It is defined as `_p2p._udp.local`. +- `host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. +- `peer-name` is the case-insensitive unique identifier of the peer, and is less than 64 characters. It is normally the base-32 encoding of peer's ID. + - If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) workaround can be used. ## Peer Discovery ### Request -To find all peers, a DNS message is sent with the question `_p2p._udp.local PTR`. Peers will then start responding with their details. +To find all peers, a DNS message is sent with the question `_p2p._udp.local PTR`. Peers will then start responding with their details. -Note that a peer must respond to it's own query. This allows other peers to passively discover it. +Note that a peer must respond to its own query. This allows other peers to passively discover it. ### Response -On receipt of a `find all peers` query, a peer sends a DNS response message (QR = 1) that contains -the **answer** +On receipt of a `find all peers` query, a peer sends a DNS response message (QR = 1) that contains the **answer** ``` PTR . ``` -The **additional records** of the response contain the peer's discovery details +The **additional records** of the response contain the peer's discovery details: ``` . TXT "dnsaddr=..." ``` -The TXT record contains the multiaddresses that the peer is listening on. Each multiaddress is a TXT attribute with the form `dnsaddr=.../p2p/QmId`. Multiple `dnsaddr` attributes and/or TXT records are allowed. +The TXT record contains the multiaddresses that the peer is listening on. Each multiaddress is a TXT attribute with the form `dnsaddr=/.../p2p/QmId`. Multiple `dnsaddr` attributes and/or TXT records are allowed. ## DNS Service Discovery -DNS-SD support is not needed for peers to discover each other. However, it is extremely usefull for network administrators to discover what is running on the network. +DNS-SD support is not needed for peers to discover each other. However, it is extremely useful for network administrators to discover what is running on the network. ### Meta Query -This allows discovery of all services. The question is `_services._dns-sd._udp.local PTR`. +This allows discovery of all services. The question is `_services._dns-sd._udp.local PTR`. A peer responds with the answer @@ -69,7 +65,7 @@ On receipt of a `find all peers` query, the following **additional records** sho ### Gotchas -Many existing tools ignore the Additional Records and always send individual queries for the peer's discovery details. To accomodate this, a peer should respond to the following queries: +Many existing tools ignore the Additional Records, and always send individual queries for the peer's discovery details. To accomodate this, a peer should respond to the following queries: - `. SRV` - `. TXT` @@ -78,7 +74,7 @@ Many existing tools ignore the Additional Records and always send individual que ## Issues -MDNS requires link local addresses. Loopback and "nat busting" addresses should not sent and must be ignored on receipt? +[ ] mDNS requires link-local addresses. Loopback and "NAT busting" addresses should not sent and must be ignored on receipt? ## References @@ -87,35 +83,43 @@ MDNS requires link local addresses. Loopback and "nat busting" addresses should - [RFC 6763 - DNS-Based Service Discovery](https://tools.ietf.org/html/rfc6763) - [Multiaddr](https://github.com/multiformats/multiaddr) -## Worked Example +## Worked Examples -Asumming that `peer-id` is `QmQusTXc1Z9C1mzxsqC9ZTFXCgSkpBRGgW4Jk2QYHxKE22`. Then the `peer-name` is `ciqcmoputolsfsigvm7nx5fwkko2eq26h46qhbj6o4co7uyn2f2srdy`. +Asumming that `peer-id` is `QmQusTXc1Z9C1mzxsqC9ZTFXCgSkpBRGgW4Jk2QYHxKE22`, then the `peer-name` is `ciqcmoputolsfsigvm7nx5fwkko2eq26h46qhbj6o4co7uyn2f2srdy` (base32 encoding of the peer ID). To make the examples more readable `id` and `name` are used. ### Meta Query -Find all services on the local network. +Goal: find all services on the local network. #### Question -`_services._dns-sd._udp.local PTR` +``` +_services._dns-sd._udp.local PTR +``` #### Answer +``` _services._dns-sd._udp.local IN PTR _p2p._udp.local +``` ### Find All Peers -Find all peers on the local network +Goal: find all peers on the local network. #### Question +``` _p2p._udp.local PTR +``` #### Answer +``` _p2p._udp.local IN PTR `name`._p2p._udp.local +``` #### Additional Records From 4c5a459ae8fb9a250e5f87f0c64fadaa7997266a Mon Sep 17 00:00:00 2001 From: Richard Schneider Date: Mon, 6 May 2019 10:47:05 +1200 Subject: [PATCH 14/14] feat: private networks --- discovery/mdns.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/discovery/mdns.md b/discovery/mdns.md index da4e7943f..4f8a014d7 100644 --- a/discovery/mdns.md +++ b/discovery/mdns.md @@ -12,8 +12,12 @@ Conceptually, it is very simple. When a peer starts (or detects a network change - `service-name` is the DNS Service Discovery (DNS-SD) service name for all peers. It is defined as `_p2p._udp.local`. - `host-name` is the fully qualified name of the peer. It is derived from the peer's name and `p2p.local`. -- `peer-name` is the case-insensitive unique identifier of the peer, and is less than 64 characters. It is normally the base-32 encoding of peer's ID. - - If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) workaround can be used. +- `peer-name` is the case-insensitive unique identifier of the peer, and is less than 64 characters. It is normally the base-32 encoding of the peer's ID. + + If the encoding of the peer's ID exceeds 63 characters, then the [Split at 63rd character](https://github.com/ipfs/in-web-browsers/issues/89#issue-341357014) workaround can be used. + +If a [private network](https://github.com/libp2p/specs/blob/master/pnet/Private-Networks-PSK-V1.md) is in use, then the `service-name` contains the base-16 encoding of the network's fingerprint as in `_p2p-X._udp.local`. +The prevents public and private networks from discovering each other's peers. ## Peer Discovery