Concept docs: nat traversal and relay #24
Conversation
ghost
assigned 
yusefnapora
changed the title
content/concepts/circuit-relay.md
Outdated
| --- | ||
|
|
||
|
|
||
| In some cases, peers will be unable to [traverse their NAT](/concepts/nat/) in a way that makes them publicly accessible. Or they may not share common [transport protocols](/concepts/transport/) that would allow them to communicate directly. |
There was a problem hiding this comment.
Not just "some" cases, it's most of the time unfortunately.
content/concepts/circuit-relay.md
Outdated
|
|
||
| In some cases, peers will be unable to [traverse their NAT](/concepts/nat/) in a way that makes them publicly accessible. Or they may not share common [transport protocols](/concepts/transport/) that would allow them to communicate directly. | ||
|
|
||
| To enable peer-to-peer architectures in the face of connectivity barriers like NAT, libp2p [defines a protocol called p2p-circuit][spec_relay]. This "circuit relay" protocol uses an intermediary peer to shuffle traffic between two peers that are unable to communicate directly. |
content/concepts/circuit-relay.md
Outdated
|
|
||
| #### AutoRelay | ||
|
|
||
| The circuit relay protocol is only effective if peers can discover willing relay peers that are accessible to both sides of the relayed connection. |
|
|
||
|
|
||
| In some cases, peers will be unable to [traverse their NAT](/concepts/nat/) in a way that makes them publicly accessible. Or they may not share common [transport protocols](/concepts/transport/) that would allow them to communicate directly. | ||
|
|
There was a problem hiding this comment.
Nit: we may not need to mention this but... well, there's an issue in libp2p we'll simply reject multiaddrs containing protocols we've never heard of (multiformats/multiaddr#70). This comment is mostly correct but, I figured I'd bring this up.
| weight: 3 | ||
| --- | ||
|
|
||
|
|
There was a problem hiding this comment.
We might want to start by simply stating what the circuit relay transport is. Something like: The circuit relay transport routes traffic between two peers over a third-party "relay" peer.
content/concepts/circuit-relay.md
Outdated
|
|
||
| To enable peer-to-peer architectures in the face of connectivity barriers like NAT, libp2p [defines a protocol called p2p-circuit][spec_relay]. This "circuit relay" protocol uses an intermediary peer to shuffle traffic between two peers that are unable to communicate directly. | ||
|
|
||
| Circuit relay is useful for any situation where peers are unable to connect directly to each other. For example, peers running in a web browser are unable to directly dial a peer over TCP. A relay supporting websockets and TCP could act as an intermediary. |
There was a problem hiding this comment.
This paragraph feels redundant with the prevoius paragraph.
content/concepts/circuit-relay.md
Outdated
| Relay connections are end-to-end encrypted, which means that the peer acting as the relay is unable to read or tamper with any traffic that flows through the connection. | ||
| {{% /notice %}} | ||
|
|
||
| An important aspect of the relay protocol is that it is not "transparent". In other words, both the source and destination are aware that traffic is being relayed. This is useful, since the destination can see the relay address used to open the connection and can potentially use it to construct a path back to the source. |
There was a problem hiding this comment.
May also want to note that it's not anonymous.
content/concepts/circuit-relay.md
Outdated
|
|
||
| #### Relay addresses | ||
|
|
||
| A "relay circuit" is identified using a [multiaddress][definition_muiltiaddress] that includes the [peer id](/concepts/peer-id/) of the peer whose traffic is being relayed (the listening peer or "relay target"). |
There was a problem hiding this comment.
We just call this "multiaddr".
|
|
||
| The most basic `p2p-circuit` address I can give out looks like this: | ||
|
|
||
| `/p2p-circuit/p2p/QmAlice` |
There was a problem hiding this comment.
I'd really avoid telling people to use this. It's useful for demos but isn't practical otherwise.
content/concepts/circuit-relay.md
Outdated
|
|
||
| AutoRelay is a feature (currently implemented in go-libp2p) that a peer can enable to attempt to discover relay peers using libp2p's [content routing](/concepts/content-routing/) interface. | ||
|
|
||
| When AutoRelay is enabled, a peer will try to discover one or more public relays and open relayed connections. If successful, the peer will advertise the relay addresses using the libp2p's [peer routing](/concepts/peer-routing/) system. |
There was a problem hiding this comment.
Also note: this is experimental and doesn't currently make any attempts to protect against malicious relays refusing to forward traffic.
content/concepts/nat.md
Outdated
|
|
||
| NAT allows many machines to share a single public address, and it is essential for the continued functioning of the IPv4 protocol, which would otherwise be unable to serve the needs of the modern networked population with its 32-bit address space. | ||
|
|
||
| For example, when I connect to my home wifi, my computer gets an IPv4 address of `10.0.1.15`. This is part of a range of IP addresses reserved for internal use by private networks. When I make an outgoing connection to a public IP address, my router sends my *public* IP address, which is shared across all the machines on my home network. When the other side sends data back to that address, the router remembers to send the data to my internal address. |
There was a problem hiding this comment.
"my router replaces my private IP address with it's public IP address"
There was a problem hiding this comment.
(that's the translation part, it translates IP addresses)
This gives an overview of NAT and the ways libp2p tries to manage NAT traversal.
@Stebalien I based most of the NAT doc on this comment: libp2p/go-libp2p#375 (comment) - if you could give this a look to see if I got things right that would be sweet.
I started to put the Circuit Relay explanation in the NAT doc, but it seemed to work better on its own, since relays are useful for more than NAT traversal.
This stuff is fairly light on details about how to enable or actually use relays, which is intentional, since that's quite implementation-specific. I'd like to keep the concept docs out of implementation land where possible. That said, when we do have more usage docs, it would be good to have links back and forth from here to there.
Closes #14 and partially addresses #4 (with the exception of usage examples).