From fb34dc26f4a44c618e18389ddcb77586b25374f1 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:43:38 -0400 Subject: [PATCH 01/17] Use .md in most relative links --- content/concepts/appendix/glossary.md | 2 +- .../concepts/discovery-routing/overview.md | 8 ++++---- .../concepts/discovery-routing/rendezvous.md | 2 +- content/concepts/fundamentals/peers.md | 8 ++++---- content/concepts/fundamentals/protocols.md | 10 +++++----- content/concepts/introduction/overview.md | 20 +++++++++---------- .../concepts/multiplex/early-negotiation.md | 4 ++-- content/concepts/multiplex/mplex.md | 2 +- content/concepts/multiplex/overview.md | 12 +++++------ content/concepts/multiplex/switch.md | 2 +- content/concepts/nat/autonat.md | 2 +- content/concepts/nat/circuit-relay.md | 12 +++++------ content/concepts/nat/dcutr.md | 2 +- content/concepts/nat/hole-punching.md | 6 +++--- content/concepts/nat/overview.md | 2 +- content/concepts/secure-comm/overview.md | 6 +++--- content/concepts/secure-comm/tls.md | 2 +- .../security/security-considerations.md | 8 ++++---- .../concepts/transports/listen-and-dial.md | 18 ++++++++--------- content/concepts/transports/webrtc.md | 4 ++-- 20 files changed, 66 insertions(+), 66 deletions(-) diff --git a/content/concepts/appendix/glossary.md b/content/concepts/appendix/glossary.md index f6bbd4bc..bb57bb02 100644 --- a/content/concepts/appendix/glossary.md +++ b/content/concepts/appendix/glossary.md @@ -233,7 +233,7 @@ In addition to managing transports, the switch also coordinates the the transport layer into one that supports [protocol negotiation](/concepts/protocols/#protocol-negotiation), [stream multiplexing](#multiplexing), and -[secure communications](/concepts/secure-comms/overview). +[secure communications](/concepts/secure-comm/overview.md). Sometimes called ["swarm"](#swarm) for historical reasons. diff --git a/content/concepts/discovery-routing/overview.md b/content/concepts/discovery-routing/overview.md index 349f4346..8232dcfd 100644 --- a/content/concepts/discovery-routing/overview.md +++ b/content/concepts/discovery-routing/overview.md @@ -40,16 +40,16 @@ implementation, discovery and routing usually happen concurrently. libp2p provides a set of modules for different network-level functionality, including peer discovery and routing. Peers in libp2p can discover other peers using various mechanisms, such as exchanging peer -[multiaddresses](/concepts/fundamentals/addressing) over the +[multiaddresses](/concepts/fundamentals/addressing.md) over the network, querying a directory service, or using a distributed hash table (DHT) to store and retrieve information about available peers. These methods include, but are not limited to: -- [Rendezvous](/concepts/discovery-routing/rendezvous): a protocol that allows peers to exchange peer multiaddresses +- [Rendezvous](/concepts/discovery-routing/rendezvous.md): a protocol that allows peers to exchange peer multiaddresses in a secure and private manner. -- [mDNS](/concepts/discovery-routing/mdns): a multicast Domain Name System (DNS) protocol that allows peers to +- [mDNS](/concepts/discovery-routing/mDNS.md): a multicast Domain Name System (DNS) protocol that allows peers to discover other peers on the local network. -- [DHT](/concepts/discovery-routing/kaddht): Distributed Hash Table, libp2p uses a DHT called Kademlia, it assigns +- [DHT](/concepts/discovery-routing/kaddht.md): Distributed Hash Table, libp2p uses a DHT called Kademlia, it assigns each piece of content a unique identifier and stores the content on the peer whose identifier is closest to the content's identifier. diff --git a/content/concepts/discovery-routing/rendezvous.md b/content/concepts/discovery-routing/rendezvous.md index 1ee6dbee..934297a3 100644 --- a/content/concepts/discovery-routing/rendezvous.md +++ b/content/concepts/discovery-routing/rendezvous.md @@ -73,7 +73,7 @@ The rendezvous protocol runs over libp2p streams using the protocol ID `/rendezv ### Rendezvous and publish-subscribe -For effective discovery, rendezvous can be combined with [libp2p publish/subscribe](/concepts/pubsub/overview). +For effective discovery, rendezvous can be combined with [libp2p publish/subscribe](/concepts/pubsub/overview.md). At a basic level, rendezvous can bootstrap pubsub by discovering peers subscribed to a topic. The rendezvous would be responsible for publishing packets, subscribing, or unsubscribing from packet shapes. diff --git a/content/concepts/fundamentals/peers.md b/content/concepts/fundamentals/peers.md index 90278a88..f3656a85 100644 --- a/content/concepts/fundamentals/peers.md +++ b/content/concepts/fundamentals/peers.md @@ -25,7 +25,7 @@ peers. Every private key has a corresponding public key, which is shared with other peers. Together, the public and private key (or "key pair") allow peers to establish -[secure communication](/concepts/secure-comm/overview) channels with each other. +[secure communication](/concepts/secure-comm/overview.md) channels with each other. Conceptually, a Peer ID is a [cryptographic hash][wiki_hash_function] of a peer's public key. When peers establish a secure channel, the hash can be used to @@ -66,7 +66,7 @@ libp2p multiaddress for me would be: As with other multiaddrs, a `/p2p` address can be encapsulated into another multiaddr to compose into a new multiaddr. For example, I can combine -the above with a [transport](/concepts/transport/) address +the above with a [transport](/concepts/transports/overview.md) address `/ip4/198.51.100.0/tcp/4242` to produce this very useful address: ```shell @@ -119,8 +119,8 @@ un-{known, identified} peers on the peer routing guide. [wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function [wiki_base58]: https://en.wikipedia.org/wiki/Base58 -[definition_multiaddr]: /concepts/appendix/glossary/#multiaddr -[definition_multihash]: /concepts/appendix/glossary/#multihash +[definition_multiaddr]: /concepts/appendix/glossary.md#multiaddr +[definition_multihash]: /concepts/appendix/glossary.md#multihash [spec_peerid]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md [identity]: https://github.com/libp2p/specs/blob/master/identify/README.md#identifypush diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index 7349ca24..827c7bf1 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -11,7 +11,7 @@ There are protocols everywhere you look when you're writing network applications especially thick with them. The kind of protocols this article is concerned with are the ones built with libp2p itself, -using the core libp2p abstractions like [transport](/concepts/transport), [peer identity](/concepts/peers#peer-id/), [addressing](/concepts/addressing/), and so on. +using the core libp2p abstractions like [transport](/concepts/transports/overview.md), [peer identity](/concepts/fundamentals/peers.md#peer-id), [addressing](/concepts/fundamentals/addressing.md), and so on. Throughout this article, we'll call this kind of protocol that is built with libp2p a **libp2p protocol**, but you may also see them referred to as "wire protocols" or "application protocols". @@ -65,8 +65,8 @@ properties: - Supports backpressure - Readers can't be flooded by eager writers -Behind the scenes, libp2p will also ensure that the stream is [secure](/concepts/secure-comms/) and efficiently -[multiplexed](/concepts/stream-multiplexing/). This is transparent to the protocol handler, which reads and writes +Behind the scenes, libp2p will also ensure that the stream is [secure](/concepts/secure-comm/overview.md) and efficiently +[multiplexed](/concepts/multiplex/overview.md). This is transparent to the protocol handler, which reads and writes unencrypted binary data over the stream. The format of the binary data and the mechanics of what to send when and by whom are all up to the protocol to determine. For inspiration, some [common patterns](#common-patterns) that are used in libp2p's internal protocols are outlined below. @@ -210,5 +210,5 @@ for tunneling traffic through relay peers when two peers are unable to connect t directly. See the article for more information on working with relays, including notes on relay addresses and how to enable automatic relay connection when behind an intractable NAT. -[definition_switch]: /reference/glossary/#switch -[definition_multiaddr]: /reference/glossary/#multiaddr +[definition_switch]: /concepts/appendix/glossary.md#switch +[definition_multiaddr]: /concepts/appendix/glossary.md#multiaddr diff --git a/content/concepts/introduction/overview.md b/content/concepts/introduction/overview.md index 0d4ae91e..915ba8f2 100644 --- a/content/concepts/introduction/overview.md +++ b/content/concepts/introduction/overview.md @@ -22,7 +22,7 @@ has something for you. {{< alert icon="" context="">}} If you have any questions or suggestions as you navigate the documentation, -please don't hesitate to [reach out](/concepts/contribute/community), or help +please don't hesitate to [reach out](/concepts/contribute/community.md), or help improve the documentation by [contributing to the site](https://github.com/libp2p/docs). {{< /alert >}} @@ -36,7 +36,7 @@ libp2p, (short for "library peer-to-peer") is a peer-to-peer (P2P) networking framework that enables the development of P2P applications. It consists of a collection of protocols, specifications, and libraries that facilitate P2P communication between network participants, known as -"[peers](/concepts/fundamentals/peers)." +"[peers](/concepts/fundamentals/peers.md)." ### Peer-to-peer basics @@ -85,7 +85,7 @@ There are several reasons to consider using libp2p as a networking layer to crea to fit the specific requirements of any P2P application. - **Extensive transport configurability**: libp2p provides a set of specifications that can be adapted to - support various [transport protocols](/concepts/transports/overview), allowing libp2p applications to operate + support various [transport protocols](/concepts/transports/overview.md), allowing libp2p applications to operate in various runtime and networking environments as the wealth of transport protocol choices makes it possible to use libp2p in a variety of scenarios. @@ -94,19 +94,19 @@ There are several reasons to consider using libp2p as a networking layer to crea [implemented in many programming languages](https://libp2p.io/implementations/), providing developers with great flexibility when building P2P applications. -- **Security**: libp2p includes [several security features](/concepts/security/security-considerations), +- **Security**: libp2p includes [several security features](/concepts/security/security-considerations.md), such as peer identity verification using public key cryptography and - [encrypted communication](/concepts/secure-comm/overview) between peers using modern cryptographic algorithms. + [encrypted communication](/concepts/secure-comm/overview.md) between peers using modern cryptographic algorithms. - **Robustness**: libp2p is a robust and reliable networking protocol that is designed to withstand stress, disturbance, and change. Its features and design choices ensure that it is able to function effectively and efficiently in a wide range of environments, and it is able to recover quickly from disruptions or failures. It also offers protection against network attacks through the use of - [mitigation techniques](/concepts/security/dos-mitigation). + [mitigation techniques](/concepts/security/dos-mitigation.md). - **Resiliency**: P2P networks are often more resilient than traditional client-server networks, as there is no single point of failure. libp2p includes features such as - [peer discovery and content routing](/concepts/discovery-routing/overview/) that help + [peer discovery and content routing](/concepts/discovery-routing/overview.md) that help to ensure that the network remains available and accessible even if some peers are offline or unreachable. - **Efficiency**: P2P networks can be more efficient in resource utilization, as data is @@ -114,15 +114,15 @@ There are several reasons to consider using libp2p as a networking layer to crea and retrieval patterns that allow developers to distribute data efficiently across the network, making it possible to store and retrieve data in a cost-effective and scalable way. -- **Piercing NAT Barriers**: libp2p is equipped with capabilities for [NAT traversal](/concepts/nat/overview), +- **Piercing NAT Barriers**: libp2p is equipped with capabilities for [NAT traversal](/concepts/nat/overview.md), which allows P2P communication between peers even when they are behind NAT devices or firewalls. This helps to maintain the connectivity of the network and ensure that it remains accessible despite the presence of these obstacles. - **Message Distribution and Dissemination**: One such pattern libp2p uses is - [publish/subscribe (pubsub)](/concepts/pubsub/overview), which allows a sender (publisher) to send a message + [publish/subscribe (pubsub)](/concepts/pubsub/overview.md), which allows a sender (publisher) to send a message to multiple recipients (subscribers) without the publisher having to know who the subscribers are. - libp2p implements pubsub through the use of protocols like [gossipsub](/concepts/pubsub/overview/#gossip), providing + libp2p implements pubsub through the use of protocols like [gossipsub](/concepts/pubsub/overview.md#gossip), providing developers with a flexible and efficient means of exchanging data and messages within their P2P applications. diff --git a/content/concepts/multiplex/early-negotiation.md b/content/concepts/multiplex/early-negotiation.md index d08bf88f..c4da7718 100644 --- a/content/concepts/multiplex/early-negotiation.md +++ b/content/concepts/multiplex/early-negotiation.md @@ -21,9 +21,9 @@ second [is shown in a diagram here](https://github.com/libp2p/specs/tree/master/connections#upgrading-connections). First, the security protocol is negotiated, then this protocol is used to perform a cryptographic -handshake. libp2p currently supports [Noise](/concepts/secure-comm/noise) and [TLS 1.3](/concepts/secure-comm/tls). +handshake. libp2p currently supports [Noise](/concepts/secure-comm/noise.md) and [TLS 1.3](/concepts/secure-comm/tls.md). Once the cryptographic handshake completes, multistream-select runs again on top of -the secured connection to negotiate a steam multiplexer, like [yamux](/concepts/multiplex/yamux) or [mplex](/concepts/multiplex/mplex). +the secured connection to negotiate a steam multiplexer, like [yamux](/concepts/multiplex/yamux.md) or [mplex](/concepts/multiplex/mplex.md). diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 8bcbdd7f..b0c4d709 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -13,7 +13,7 @@ is now considered critical for a stream multiplexer. mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection. Peers can open, write to, close, and reset a stream. mplex uses a message-based framing -layer like [yamux](/concepts/multiplex/yamux), enabling it to multiplex different +layer like [yamux](/concepts/multiplex/yamux.md), enabling it to multiplex different data streams, including stream-oriented data and other types of messages. ### Drawbacks diff --git a/content/concepts/multiplex/overview.md b/content/concepts/multiplex/overview.md index e76dd888..df4ec9fd 100644 --- a/content/concepts/multiplex/overview.md +++ b/content/concepts/multiplex/overview.md @@ -51,10 +51,10 @@ and allowing for the seamless transmission of multiple streams of data over a si connection. {{< /alert >}} -Currently, libp2p supports two stream muxers, [mplex](/concepts/multiplex/mplex) -and [yamux](/concepts/multiplex/yamux). However, many of the -[transport protocols](/concepts/transports/overview) available in the libp2p stack -come with native streams, such as [QUIC](/concepts/transports/quic), -[WebTransport](/concepts/transports/webtransport), and -[WebRTC](/concepts/transports/webrtc), and in these cases, libp2p +Currently, libp2p supports two stream muxers, [mplex](/concepts/multiplex/mplex.md) +and [yamux](/concepts/multiplex/yamux.md). However, many of the +[transport protocols](/concepts/transports/overview.md) available in the libp2p stack +come with native streams, such as [QUIC](/concepts/transports/quic.md), +[WebTransport](/concepts/transports/webtransport.md), and +[WebRTC](/concepts/transports/webrtc.md), and in these cases, libp2p **does not need to perform stream multiplexing** as the protocol already provides it. diff --git a/content/concepts/multiplex/switch.md b/content/concepts/multiplex/switch.md index 72acc39b..7f98707c 100644 --- a/content/concepts/multiplex/switch.md +++ b/content/concepts/multiplex/switch.md @@ -9,4 +9,4 @@ libp2p maintains some state about known peers and existing connections in a comp When configuring libp2p, applications enable stream muxing modules, which the switch will use when dialing peers and listening for connections. If the remote peers support any of the same stream muxing implementations, the switch will select and use it when establishing the connection. If you dial a peer that the switch already has an open connection to, the new stream will automatically be multiplexed over the existing connection. -Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation](/concepts/fundamentals/protocols/#protocol-negotiation) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams. +Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation](/concepts/fundamentals/protocols.md#protocol-negotiation) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams. diff --git a/content/concepts/nat/autonat.md b/content/concepts/nat/autonat.md index 84125387..ee7e5a4d 100644 --- a/content/concepts/nat/autonat.md +++ b/content/concepts/nat/autonat.md @@ -65,7 +65,7 @@ whether or not it is behind a NAT. > If the response indicates success, the node is likely not behind a NAT and does > not need to use a relay server to improve its connectivity. If the response indicates > an error, the node is likely behind a NAT and may need to use a -> [relay server](/concepts/autonat/dcutr) to communicate with other nodes in the network. +> [relay server](/concepts/nat/dcutr.md) to communicate with other nodes in the network. {{< alert icon="" context="caution">}} To prevent diff --git a/content/concepts/nat/circuit-relay.md b/content/concepts/nat/circuit-relay.md index fe4b94e2..ae1d2ae5 100644 --- a/content/concepts/nat/circuit-relay.md +++ b/content/concepts/nat/circuit-relay.md @@ -9,9 +9,9 @@ aliases: ## What is Circuit Relay? -Circuit relay is a [transport protocol](/concepts/transports/overview) that routes traffic between two peers over a third-party "relay" peer. +Circuit relay is a [transport protocol](/concepts/transports/overview.md) that routes traffic between two peers over a third-party "relay" peer. -In many cases, peers will be unable to [traverse their NAT and/or firewall](/concepts/overview) in a way that makes them publicly accessible. Or they may not share common [transport protocols](/concepts/transports/overview) that would allow them to communicate directly. +In many cases, peers will be unable to [traverse their NAT and/or firewall](/concepts/nat/overview.md) in a way that makes them publicly accessible. Or they may not share common [transport protocols](/concepts/transports/overview.md) 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]. When a peer isn't able to listen on a public address, it can dial out to a relay peer, which will keep a long-lived connection open. Other peers will be able to dial through the relay peer using a `p2p-circuit` address, which will forward traffic to its destination. @@ -30,7 +30,7 @@ Today there are two versions of the circuit relay protocol, [v1](https://github. ## Relay addresses -A relay circuit is identified using a [multiaddr][definition_muiltiaddress] that includes the [Peer ID](/concepts/fundamentals/peers#peer-id) of the peer whose traffic is being relayed (the listening peer or "relay target"). +A relay circuit is identified using a [multiaddr][definition_muiltiaddress] that includes the [Peer ID](/concepts/fundamentals/peers.md#peer-id) of the peer whose traffic is being relayed (the listening peer or "relay target"). Let's say that I have a peer with the Peer ID `QmAlice`. I want to give out my address to my friend `QmBob`, but I'm behind a NAT that won't let anyone dial me directly. @@ -38,7 +38,7 @@ The most basic `p2p-circuit` address I can construct looks like this: `/p2p-circuit/p2p/QmAlice` -The address above is interesting, because it doesn't include any [transport](/concepts/transports/overview) addresses for either the peer we want to contact (`QmAlice`) or for the relay peer that will convey the traffic. Without that information, the only chance a peer has of dialing me is to discover a relay and hope they have a connection to me. +The address above is interesting, because it doesn't include any [transport](/concepts/transports/overview.md) addresses for either the peer we want to contact (`QmAlice`) or for the relay peer that will convey the traffic. Without that information, the only chance a peer has of dialing me is to discover a relay and hope they have a connection to me. A better address would be something like `/p2p/QmRelay/p2p-circuit/p2p/QmAlice`. This includes the identity of a specific relay peer, `QmRelay`. If a peer already knows how to open a connection to `QmRelay`, they'll be able to reach us. @@ -60,10 +60,10 @@ The below sequence diagram depicts a sample relay process: ![Circuit v2 Protocol Interaction](https://raw.githubusercontent.com/libp2p/specs/master/relay/circuit-v2.svg) -1. Node `A` is behind a NAT and/or firewall, e.g. detected via the [AutoNAT service](/concepts/autonat). +1. Node `A` is behind a NAT and/or firewall, e.g. detected via the [AutoNAT service](/concepts/nat/autonat.md). 2. Node `A` therefore requests a reservation with relay `R`. I.e. node `A` asks relay `R` to listen for incoming connections on its behalf. 3. Node `B` wants to establish a connection to node `A`. Given that node `A` does not advertise any direct addresses but only a relay address, node `B` connects to relay `R`, asking relay `R` to relay a connection to `A`. 4. Relay `R` forwards the connection request to node `A` and eventually relays all data send by `A` and `B`. [spec_relay]: https://github.com/libp2p/specs/tree/master/relay -[definition_muiltiaddress]: /concepts/appendix/glossary/#multiaddr +[definition_muiltiaddress]: /concepts/appendix/glossary.md#multiaddr diff --git a/content/concepts/nat/dcutr.md b/content/concepts/nat/dcutr.md index 3e8244c0..2cf11dd0 100644 --- a/content/concepts/nat/dcutr.md +++ b/content/concepts/nat/dcutr.md @@ -8,7 +8,7 @@ weight: 210 Relays are used to traverse NATs by acting as proxies, but this can be expensive to scale and maintain, and may result in low-bandwidth, high-latency -connections. [Hole punching](/concepts/nat/hole-punching) is another technique +connections. [Hole punching](/concepts/nat/hole-punching.md) is another technique that enables NAT traversal by enabling two nodes behind NATs to communicate directly. However, in addition to relay nodes, it requires another piece of infrastructure called signaling servers. diff --git a/content/concepts/nat/hole-punching.md b/content/concepts/nat/hole-punching.md index 3c78350f..a536a6e5 100644 --- a/content/concepts/nat/hole-punching.md +++ b/content/concepts/nat/hole-punching.md @@ -97,7 +97,7 @@ a hole punching phase. ### Phase I: Preparation -1. [AutoNAT](/concepts/autonat): Determine whether a node is dialable, +1. [AutoNAT](/concepts/nat/autonat.md): Determine whether a node is dialable, as in, discover if a node is behind a NAT or firewall. > This is equivalent to the @@ -131,7 +131,7 @@ a hole punching phase. for the closest peers to its Peer ID or choose a subset of the public nodes it is already connected to. -2. [Circuit Relay](/concepts/circuit-relay): Connect to and request +2. [Circuit Relay](/concepts/nat/circuit-relay.md): Connect to and request reservations with the discovered relay nodes. A node can advertise itself as being reachable through a remote relay node. @@ -152,7 +152,7 @@ a hole punching phase. ### Phase II: Hole punching -1. [Circuit Relay](/concepts/circuit-relay): Establish a secure relay connection +1. [Circuit Relay](/concepts/nat/circuit-relay.md): Establish a secure relay connection through the public relay node. Node `A` establishes a direct connection with the relay node. Node `B` then requests a relayed connection to node `A` through the relay node, creating a bi-directional channel and uses TLS to secure the diff --git a/content/concepts/nat/overview.md b/content/concepts/nat/overview.md index 3f3ceae9..01a88e7c 100644 --- a/content/concepts/nat/overview.md +++ b/content/concepts/nat/overview.md @@ -8,7 +8,7 @@ aliases: ## Overview -The internet is composed of countless networks, bound together into shared address spaces by foundational [transport protocols](/concepts/transport/overview). +The internet is composed of countless networks, bound together into shared address spaces by foundational [transport protocols](/concepts/transports/overview.md). As traffic moves between network boundaries, it's very common for a process called Network Address Translation to occur. Network Address Translation (NAT) maps an address from one address space to another. diff --git a/content/concepts/secure-comm/overview.md b/content/concepts/secure-comm/overview.md index c24eae2b..283fc1e5 100644 --- a/content/concepts/secure-comm/overview.md +++ b/content/concepts/secure-comm/overview.md @@ -12,12 +12,12 @@ Before two peers can transmit data, the communication channel they establish needs to be secured. By design, libp2p supports many different transports (TCP, QUIC, WebSocket, WebTransport, etc.). Some transports have built-in encryption at the transport layer -like [QUIC](/concepts/transports/quic), while other transports (e.g. TCP, WebSocket) +like [QUIC](/concepts/transports/quic.md), while other transports (e.g. TCP, WebSocket) lack native security and require a security handshake after the transport connection has been established. ## Secure channels in libp2p -libp2p specifies two security protocols, [TLS 1.3](/concepts/secure-comm/tls) and [Noise](/concepts/secure-comm/noise). +libp2p specifies two security protocols, [TLS 1.3](/concepts/secure-comm/tls.md) and [Noise](/concepts/secure-comm/noise.md). After the handshake has finished, we need to negotiate a -[stream multiplexer](/concepts/multiplex/overview) for the connection. +[stream multiplexer](/concepts/multiplex/overview.md) for the connection. diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 8d50b53a..71a0d594 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -7,7 +7,7 @@ aliases: --- TLS (Transport Layer Security) is one of the security handshakes used to secure transports -that don't have built-in security (e.g. TCP, WebSocket). [Noise](/concepts/secure-comm/noise), an alternative to +that don't have built-in security (e.g. TCP, WebSocket). [Noise](/concepts/secure-comm/noise.md), an alternative to TLS, is also another security handshake used to secure transports. ## What is TLS? diff --git a/content/concepts/security/security-considerations.md b/content/concepts/security/security-considerations.md index c1775944..4c0642e9 100644 --- a/content/concepts/security/security-considerations.md +++ b/content/concepts/security/security-considerations.md @@ -29,7 +29,7 @@ reasonably succeed. ## Identity and Trust -Every libp2p peer is uniquely identified by their [Peer ID](/concepts/fundamentals/peers#peer-id), which +Every libp2p peer is uniquely identified by their [Peer ID](/concepts/fundamentals/peers.md#peer-id), which is derived from a private cryptographic key. Peer ids and their corresponding keys allow us to _authenticate_ remote peers, so that we can be sure we're talking to the correct peer and not an imposter. @@ -48,7 +48,7 @@ To design an authorization system on libp2p, you can rely on the authentication of peer ids and build an association between peer ids and permissions, with the Peer ID serving the same function as the "username" in traditional authorization frameworks, and the peer's private key serving as the "password". -Your [protocol handler](/concepts/fundamentals/protocols/#handler-functions) could then +Your [protocol handler](/concepts/fundamentals/protocols.md/#handler-functions) could then reject requests from untrusted peers. Of course, it's also possible to build other kinds of authorization systems on @@ -141,7 +141,7 @@ returning dishonest routing information. ### Publish / Subscribe -libp2p's [publish/subscribe protocol](/concepts/pubsub/overview) allows a peer +libp2p's [publish/subscribe protocol](/concepts/pubsub/overview.md) allows a peer to broadcast messages to other peers within a given "topic." By default, the `gossipsub` implementation will sign all messages with the @@ -159,6 +159,6 @@ attacks. We expect this to lead to a more robust and attack-resistant pubsub protocol, but it is unlikely to prevent all classes of possible attack by determined bad actors. -[glossary-dht]: /concepts/appendix/glossary/#dht +[glossary-dht]: /concepts/appendix/glossary.md#dht [wikipedia-sybil]: https://en.wikipedia.org/wiki/Sybil_attack [paper-s-kademlia]: https://telematics.tm.kit.edu/publications/Files/267/SKademlia_2007.pdf diff --git a/content/concepts/transports/listen-and-dial.md b/content/concepts/transports/listen-and-dial.md index 154d2ef6..e2c0f57c 100644 --- a/content/concepts/transports/listen-and-dial.md +++ b/content/concepts/transports/listen-and-dial.md @@ -28,7 +28,7 @@ reach them. Because each transport will likely require its own address scheme, libp2p uses a convention called a "multiaddress" or `multiaddr` to encode many different addressing schemes. -The [addressing doc](/concepts/fundamentals/addressing) goes into more detail, but an overview +The [addressing doc](/concepts/fundamentals/addressing.md) goes into more detail, but an overview of how multiaddresses work is helpful for understanding the dial and listen interfaces. @@ -43,15 +43,15 @@ has the advantage of being explicit about the protocols that are being described. With the multiaddr, you can see at a glance that the `198.51.100.0` address belongs to the IPv4 protocol, and the `6543` belongs to TCP. -For more complex examples, see [addressing](/concepts/fundamentals/addressing). +For more complex examples, see [addressing](/concepts/fundamentals/addressing.md). Both dial and listen deal with multiaddresses. When listening, you give the transport the address you'd like to listen on, and when dialing you provide the address to dial to. When dialing a remote peer, the multiaddress should include the -[PeerId](/concepts/fundamentals/peers#peer-id) of the peer you're trying to reach. -This lets libp2p establish a [secure communication channel](/concepts/secure-comm/overview) +[PeerId](/concepts/fundamentals/peers.md#peer-id) of the peer you're trying to reach. +This lets libp2p establish a [secure communication channel](/concepts/secure-comm/overview.md) and prevents impersonation. An example multiaddress that includes a `PeerId`: @@ -62,7 +62,7 @@ An example multiaddress that includes a `PeerId`: The `/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6` component uniquely identifies the remote peer using the hash of its public key. -For more, see the [peer identity content](/concepts/fundamentals/peers#peer-id). +For more, see the [peer identity content](/concepts/fundamentals/peers.md#peer-id). {{< alert icon="💡" context="tip">}} When peer routing is enabled, you can dial peers using just their PeerId, @@ -78,9 +78,9 @@ in a web browser. The libp2p component responsible for managing the transports is called the [switch][definition_switch], which also coordinates -[protocol negotiation](/concepts/fundamentals/protocols/#protocol-negotiation), -[stream multiplexing](/concepts/multiplex/overview), -[establishing secure communication](/concepts/secure-comm/overview) and other forms of +[protocol negotiation](/concepts/fundamentals/protocols.md#protocol-negotiation), +[stream multiplexing](/concepts/multiplex/overview.md), +[establishing secure communication](/concepts/secure-comm/overview.md) and other forms of "connection upgrading". The switch provides a single "entry point" for dialing and listening, and frees @@ -89,4 +89,4 @@ and other pieces of the "connection stack" that are used under the hood. {{< alert icon="💡" context="note" text="The term \"swarm\" was previously used to refer to what is now called the \"switch\", and some places in the codebase still use the \"swarm\" terminology." />}} -[definition_switch]: /concepts/appendix/glossary/#switch +[definition_switch]: /concepts/appendix/glossary.md#switch diff --git a/content/concepts/transports/webrtc.md b/content/concepts/transports/webrtc.md index 5023638b..7fbff3be 100644 --- a/content/concepts/transports/webrtc.md +++ b/content/concepts/transports/webrtc.md @@ -42,7 +42,7 @@ The features employed in libp2p are: to a peer. This means libp2p can utilize data channels as a transport to send raw data to peers and enables applications to build anything they like. -- [NAT traversal](/concepts/nat/overview): WebRTC includes mechanisms (like +- [NAT traversal](/concepts/nat/overview.md): WebRTC includes mechanisms (like [ICE](https://datatracker.ietf.org/doc/rfc5245/)) to connect to nodes that run behind NATs and firewalls. In non-decentralized WebRTC, this can be facilitated by a [TURN server.](https://webrtc.org/getting-started/turn-server), @@ -97,7 +97,7 @@ When establishing a WebRTC connection, the browser and server perform a standard handshake as part of the connection setup. Of the three primary focuses of information security, a successful DTLS handshake only provides two: confidentiality and integrity. Authenticity is achieved by succeeding the -[Noise handshake](/concepts/secure-comm/noise) following the DTLS handshake. +[Noise handshake](/concepts/secure-comm/noise.md) following the DTLS handshake. From a004999abff4d271b4b70375b7c7b2fc8dc5da06 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:45:19 -0400 Subject: [PATCH 02/17] Update fundamentals links --- content/concepts/appendix/glossary.md | 6 +++--- content/concepts/fundamentals/addressing.md | 2 +- content/concepts/fundamentals/peers.md | 2 +- content/concepts/fundamentals/protocols.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/concepts/appendix/glossary.md b/content/concepts/appendix/glossary.md index bb57bb02..a0c2786b 100644 --- a/content/concepts/appendix/glossary.md +++ b/content/concepts/appendix/glossary.md @@ -61,7 +61,7 @@ For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their es Multiaddresses can be composed to describe multiple "layers" of addresses. -For more detail, see [Concepts > Addressing](/concepts/addressing/), or the [multiaddr spec](https://github.com/multiformats/multiaddr), which has links to many implementations. +For more detail, see [Addressing](/concepts/fundamentals/addressing.md), or the [multiaddr spec](https://github.com/multiformats/multiaddr), which has links to many implementations. ### Multiaddress @@ -205,7 +205,7 @@ agree upon what protocols to use. The implementation of the libp2p handshake is called [multistream-select](https://github.com/multiformats/multistream-select). -For details, see the [protocol negotiation article](/concepts/protocols/#protocol-negotiation). +For details, see the [protocol negotiation article](/concepts/fundamentals/protocols.md#protocol-negotiation). ### Stream @@ -231,7 +231,7 @@ without having to specify what transport to use. In addition to managing transports, the switch also coordinates the "connection upgrade" process, which promotes a "raw" connection from the transport layer into one that supports -[protocol negotiation](/concepts/protocols/#protocol-negotiation), +[protocol negotiation](/concepts/fundamentals/protocols.md#protocol-negotiation), [stream multiplexing](#multiplexing), and [secure communications](/concepts/secure-comm/overview.md). diff --git a/content/concepts/fundamentals/addressing.md b/content/concepts/fundamentals/addressing.md index b6337656..0fe08d22 100644 --- a/content/concepts/fundamentals/addressing.md +++ b/content/concepts/fundamentals/addressing.md @@ -17,7 +17,7 @@ For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their es Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash](/reference/glossary/#multihash) of my IPFS node's public key. {{< alert icon="💡" context="tip">}} -For more on peer identity and its relation to public key cryptography, see [Peer Identity](/concepts/peers/#peer-id/). +For more on peer identity and its relation to public key cryptography, see [Peer Identity](/concepts/fundamentals/peers.md#peer-id). {{< /alert >}} Let's say that I have the Peer ID `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` as above, and my public ip is `198.51.100.0`. I start my libp2p application and listen for connections on TCP port `4242`. diff --git a/content/concepts/fundamentals/peers.md b/content/concepts/fundamentals/peers.md index f3656a85..a157ead1 100644 --- a/content/concepts/fundamentals/peers.md +++ b/content/concepts/fundamentals/peers.md @@ -78,7 +78,7 @@ transport. If some other peer has taken over that IP address or port, it will be immediately obvious, since they will not have control over the key pair used to produce the Peer ID embedded in the address. -**For more on addresses in libp2p, see [Addressing](/concepts/addressing/)** +**For more on addresses in libp2p, see [Addressing](/concepts/fundamentals/addressing.md)** {{< alert icon="💡" context="note">}} The multiaddr protocol for libp2p addresses was originally written `/ipfs` and was later renamed to `/p2p`. diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index 827c7bf1..53a7d2e0 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -160,7 +160,7 @@ The basic identify protocol works by establishing a new stream to a peer using t shown in the table above. When the remote peer opens the new stream, they will fill out an [`Identify` protobuf message][identify_proto] containing -information about themselves, such as their public key, which is used to derive their [`PeerId`](/concepts/peers/). +information about themselves, such as their public key, which is used to derive their [`PeerId`](/concepts/fundamentals/peers.md). Importantly, the `Identify` message includes an `observedAddr` field that contains the [multiaddr][definition_multiaddr] that the peer observed the request coming in on. This helps peers determine their NAT status, since it allows them to From c2ba18768d4fce6d457f85aea2bf0aaf88741b29 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:45:53 -0400 Subject: [PATCH 03/17] Update glossary links --- content/concepts/fundamentals/addressing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/fundamentals/addressing.md b/content/concepts/fundamentals/addressing.md index 0fe08d22..bc24c7f2 100644 --- a/content/concepts/fundamentals/addressing.md +++ b/content/concepts/fundamentals/addressing.md @@ -14,7 +14,7 @@ A `multiaddress` (often abbreviated `multiaddr`), is a convention for encoding m For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their essential addressing information. The `/ip4/192.0.2.0` informs us that we want the `192.0.2.0` loopback address of the IPv4 protocol, and `/udp/1234` tells us we want to send UDP packets to port `1234`. -Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash](/reference/glossary/#multihash) of my IPFS node's public key. +Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash](/concepts/appendix/glossary.md#multihash) of my IPFS node's public key. {{< alert icon="💡" context="tip">}} For more on peer identity and its relation to public key cryptography, see [Peer Identity](/concepts/fundamentals/peers.md#peer-id). From a4e63be5a9a47c576d5d96405d63d1a54ea7ddd6 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:46:20 -0400 Subject: [PATCH 04/17] Update nat links --- content/concepts/fundamentals/addressing.md | 4 ++-- content/concepts/fundamentals/protocols.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/concepts/fundamentals/addressing.md b/content/concepts/fundamentals/addressing.md index bc24c7f2..d7ce517f 100644 --- a/content/concepts/fundamentals/addressing.md +++ b/content/concepts/fundamentals/addressing.md @@ -22,11 +22,11 @@ For more on peer identity and its relation to public key cryptography, see [Peer Let's say that I have the Peer ID `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` as above, and my public ip is `198.51.100.0`. I start my libp2p application and listen for connections on TCP port `4242`. -Now I can start [handing out multiaddrs to all my friends](/concepts/peer-routing/), of the form `/ip4/198.51.100.0/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information. +Now I can start [handing out multiaddrs to all my friends](/concepts/appendix/glossary.md#peer-routing), of the form `/ip4/198.51.100.0/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information. Now not only do my friends know where to find me, anyone they give that address to can verify that the machine on the other side is really me, or at least, that they control the private key for my `PeerId`. They also know (by virtue of the `/p2p/` protocol id) that I'm likely to support common libp2p interactions like opening connections and negotiating what application protocols we can use to communicate. That's not bad! -This can be extended to account for multiple layers of addressing and abstraction. For example, the [addresses used for circuit relay](/concepts/circuit-relay/#relay-addresses) combine transport addresses with multiple peer identities to form an address that describes a "relay circuit": +This can be extended to account for multiple layers of addressing and abstraction. For example, the [addresses used for circuit relay](/concepts/nat/circuit-relay.md#relay-addresses) combine transport addresses with multiple peer identities to form an address that describes a "relay circuit": ```shell /ip4/198.51.100.0/tcp/4242/p2p/QmRelay/p2p-circuit/p2p/QmRelayedPeer diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index 53a7d2e0..b2cc1a54 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -177,7 +177,7 @@ see what other peers observe as their public address and compare it to their own A slight variation on `identify`, the `identify/push` protocol sends the same `Identify` message, but it does so proactively instead of in response to a request. -This is useful if a peer starts listening on a new address, establishes a new [relay circuit](/concepts/circuit-relay/), or +This is useful if a peer starts listening on a new address, establishes a new [relay circuit](/concepts/nat/circuit-relay.md), or learns of its public address from other peers using the standard `identify` protocol. Upon creating or learning of a new address, the peer can push the new address to all peers it's currently aware of. This keeps everyone's routing tables up to date and makes it more likely that other peers will discover the new address. @@ -205,7 +205,7 @@ check out the [Distributed Hash Tables guide][dht] on the IPFS documentation sit [relay_js]: https://github.com/libp2p/js-libp2p-circuit [relay_go]: https://github.com/libp2p/go-libp2p-circuit -As described in the [Circuit Relay article](/concepts/circuit-relay/), libp2p provides a protocol +As described in the [Circuit Relay article](/concepts/nat/circuit-relay.md), libp2p provides a protocol for tunneling traffic through relay peers when two peers are unable to connect to each other directly. See the article for more information on working with relays, including notes on relay addresses and how to enable automatic relay connection when behind an intractable NAT. From d2a45a5ad6e9c3ee27c3d0644a4f623f194be746 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:46:37 -0400 Subject: [PATCH 05/17] Update routing link --- content/concepts/fundamentals/protocols.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index b2cc1a54..2940cccc 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -186,7 +186,7 @@ makes it more likely that other peers will discover the new address. `kad-dht` is a [Distributed Hash Table][wiki_dht] based on the [Kademlia][wiki_kad] routing algorithm, with some modifications. -libp2p uses the DHT as the foundation of its [peer routing](/concepts/peer-routing/) and [content routing](/concepts/content-routing/) functionality. To learn more about DHT and the Kademlia algorithm, +libp2p uses the DHT as the foundation of its [routing](/concepts/discovery-routing/overview.md) functionality. To learn more about DHT and the Kademlia algorithm, check out the [Distributed Hash Tables guide][dht] on the IPFS documentation site. In addition, check out the [libp2p implementations page](https://libp2p.io/implementations/) for updates on all the kad-libp2p implementations. From 26ba8645077b13328cb4f85c659e0c2c1c5baf78 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:46:56 -0400 Subject: [PATCH 06/17] Update link to identify protocol --- content/concepts/nat/autonat.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/nat/autonat.md b/content/concepts/nat/autonat.md index ee7e5a4d..fa79a905 100644 --- a/content/concepts/nat/autonat.md +++ b/content/concepts/nat/autonat.md @@ -9,7 +9,7 @@ aliases: ## Background -While the [identify protocol](/concepts/introduction/protocols/identify) +While the [identify protocol](https://github.com/libp2p/specs/blob/master/identify/README.md) allows peers to inform each other about their observed network addresses, sometimes these addresses are inaccessible as the peer may be located in a private network (i.e., behind a NAT or a firewall). From 5854746827ebfbb34aebd0602df25c9dad53a2b4 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:47:15 -0400 Subject: [PATCH 07/17] Add TODO for missing fail2ban demo video --- content/concepts/security/dos-mitigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/security/dos-mitigation.md b/content/concepts/security/dos-mitigation.md index 2b5d18a9..0f7e514f 100644 --- a/content/concepts/security/dos-mitigation.md +++ b/content/concepts/security/dos-mitigation.md @@ -358,7 +358,7 @@ User=ipfs #### Example screen recording of fail2ban in action - + [fail2ban+go-libp2p screen recording](/images/fail2bango-libp2p.mp4) #### Setting Up fail2ban From f66321d02b72c92dfd0e3dbcb357280cfeb5d3a4 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:48:43 -0400 Subject: [PATCH 08/17] Fix filecoin slack link --- content/concepts/contribute/community.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/contribute/community.md b/content/concepts/contribute/community.md index 12f4a823..a75f167e 100644 --- a/content/concepts/contribute/community.md +++ b/content/concepts/contribute/community.md @@ -11,4 +11,4 @@ We love talking about libp2p, and we'd be happy to have you in the mix. Visit our [discussion forums](https://discuss.libp2p.io) to ask questions about [using libp2p](https://discuss.libp2p.io/c/users), discuss exciting [research](https://discuss.libp2p.io/c/research), and [stay up to date with important announcements](https://discuss.libp2p.io/c/news). -We also hang out in the #libp2p-implementers channel in the [Filecoin slack](https://http://filecoin.io/slack). +We also hang out in the #libp2p-implementers channel in the [Filecoin slack](https://filecoin.io/slack). From 1d391ffc6e0bfc2d6dfebd19722291117dec34ac Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Thu, 3 Aug 2023 22:52:28 -0400 Subject: [PATCH 09/17] Enable link check CI --- .github/workflows/link-check.yml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 8e5f09bb..28f87f1c 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -1,7 +1,10 @@ name: links on: - workflow_dispatch: + push: + branches: master + pull_request: + branches: master jobs: linkChecker: @@ -10,10 +13,11 @@ jobs: - uses: actions/checkout@v3 - name: Link Checker - uses: lycheeverse/lychee-action@ec3ed119d4f44ad2673a7232460dc7dff59d2421 # v1.8.0 + uses: lycheeverse/lychee-action@v1.8.0 with: # Check all markdown in /content/ - args: --verbose --no-progress './content/' + # Ignore twitter.com links because they all 503 unless logged in + args: --no-progress --base ./content --exclude twitter.com ./content fail: true env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} From 824e60b1c6c8b2e100b821345d96438e5612a76b Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Mon, 7 Aug 2023 19:23:36 -0400 Subject: [PATCH 10/17] Use hugo ref tags for internal links --- content/concepts/appendix/glossary.md | 8 ++++---- .../concepts/discovery-routing/overview.md | 8 ++++---- .../concepts/discovery-routing/rendezvous.md | 6 +++--- content/concepts/fundamentals/addressing.md | 8 ++++---- content/concepts/fundamentals/peers.md | 6 +++--- content/concepts/fundamentals/protocols.md | 14 ++++++------- content/concepts/introduction/overview.md | 20 +++++++++---------- .../concepts/multiplex/early-negotiation.md | 4 ++-- content/concepts/multiplex/mplex.md | 2 +- content/concepts/multiplex/overview.md | 12 +++++------ content/concepts/multiplex/switch.md | 2 +- content/concepts/nat/autonat.md | 2 +- content/concepts/nat/circuit-relay.md | 12 +++++------ content/concepts/nat/dcutr.md | 4 ++-- content/concepts/nat/hole-punching.md | 6 +++--- content/concepts/nat/overview.md | 2 +- content/concepts/secure-comm/overview.md | 6 +++--- content/concepts/secure-comm/tls.md | 2 +- content/concepts/security/dos-mitigation.md | 4 ++-- .../security/security-considerations.md | 6 +++--- .../concepts/transports/listen-and-dial.md | 16 +++++++-------- content/concepts/transports/quic.md | 2 +- content/concepts/transports/webrtc.md | 4 ++-- 23 files changed, 78 insertions(+), 78 deletions(-) diff --git a/content/concepts/appendix/glossary.md b/content/concepts/appendix/glossary.md index a0c2786b..454bb396 100644 --- a/content/concepts/appendix/glossary.md +++ b/content/concepts/appendix/glossary.md @@ -61,7 +61,7 @@ For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their es Multiaddresses can be composed to describe multiple "layers" of addresses. -For more detail, see [Addressing](/concepts/fundamentals/addressing.md), or the [multiaddr spec](https://github.com/multiformats/multiaddr), which has links to many implementations. +For more detail, see [Addressing]({{< ref "/concepts/fundamentals/addressing.md" >}}), or the [multiaddr spec](https://github.com/multiformats/multiaddr), which has links to many implementations. ### Multiaddress @@ -205,7 +205,7 @@ agree upon what protocols to use. The implementation of the libp2p handshake is called [multistream-select](https://github.com/multiformats/multistream-select). -For details, see the [protocol negotiation article](/concepts/fundamentals/protocols.md#protocol-negotiation). +For details, see the [protocol negotiation article]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}). ### Stream @@ -231,9 +231,9 @@ without having to specify what transport to use. In addition to managing transports, the switch also coordinates the "connection upgrade" process, which promotes a "raw" connection from the transport layer into one that supports -[protocol negotiation](/concepts/fundamentals/protocols.md#protocol-negotiation), +[protocol negotiation]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}), [stream multiplexing](#multiplexing), and -[secure communications](/concepts/secure-comm/overview.md). +[secure communications]({{< ref "/concepts/secure-comm/overview.md" >}}). Sometimes called ["swarm"](#swarm) for historical reasons. diff --git a/content/concepts/discovery-routing/overview.md b/content/concepts/discovery-routing/overview.md index 8232dcfd..a9a4ec9d 100644 --- a/content/concepts/discovery-routing/overview.md +++ b/content/concepts/discovery-routing/overview.md @@ -40,16 +40,16 @@ implementation, discovery and routing usually happen concurrently. libp2p provides a set of modules for different network-level functionality, including peer discovery and routing. Peers in libp2p can discover other peers using various mechanisms, such as exchanging peer -[multiaddresses](/concepts/fundamentals/addressing.md) over the +[multiaddresses]({{< ref "/concepts/fundamentals/addressing.md" >}}) over the network, querying a directory service, or using a distributed hash table (DHT) to store and retrieve information about available peers. These methods include, but are not limited to: -- [Rendezvous](/concepts/discovery-routing/rendezvous.md): a protocol that allows peers to exchange peer multiaddresses +- [Rendezvous]({{< ref "/concepts/discovery-routing/rendezvous.md" >}}): a protocol that allows peers to exchange peer multiaddresses in a secure and private manner. -- [mDNS](/concepts/discovery-routing/mDNS.md): a multicast Domain Name System (DNS) protocol that allows peers to +- [mDNS]({{< ref "/concepts/discovery-routing/mDNS.md" >}}): a multicast Domain Name System (DNS) protocol that allows peers to discover other peers on the local network. -- [DHT](/concepts/discovery-routing/kaddht.md): Distributed Hash Table, libp2p uses a DHT called Kademlia, it assigns +- [DHT]({{< ref "/concepts/discovery-routing/kaddht.md" >}}): Distributed Hash Table, libp2p uses a DHT called Kademlia, it assigns each piece of content a unique identifier and stores the content on the peer whose identifier is closest to the content's identifier. diff --git a/content/concepts/discovery-routing/rendezvous.md b/content/concepts/discovery-routing/rendezvous.md index 934297a3..a010326a 100644 --- a/content/concepts/discovery-routing/rendezvous.md +++ b/content/concepts/discovery-routing/rendezvous.md @@ -23,11 +23,11 @@ serve as a hub for nodes to discover. solutions like DHT and Gossipsub. DHT (Distributed Hash Table) and Gossipsub are decentralized alternatives to Rendezvous. - [DHT](/concepts/discovery-routing/kaddht.md) is a distributed network protocol used to store and + [DHT]({{< ref "/concepts/discovery-routing/kaddht.md" >}}) is a distributed network protocol used to store and retrieve data in a P2P network efficiently. It is like a hash table mapping keys to values, allowing for fast lookups and efficient data distribution across the network. - [Gossipsub](/concepts/pubsub/overview.md), on the other hand, is a pub-sub (publish-subscribe) protocol + [Gossipsub]({{< ref "/concepts/pubsub/overview.md" >}}), on the other hand, is a pub-sub (publish-subscribe) protocol that is used to distribute messages and data across a network. It uses a gossip-based mechanism to propagate messages throughout the network, allowing fast and efficient distribution without relying on a central control point. @@ -73,7 +73,7 @@ The rendezvous protocol runs over libp2p streams using the protocol ID `/rendezv ### Rendezvous and publish-subscribe -For effective discovery, rendezvous can be combined with [libp2p publish/subscribe](/concepts/pubsub/overview.md). +For effective discovery, rendezvous can be combined with [libp2p publish/subscribe]({{< ref "/concepts/pubsub/overview.md" >}}). At a basic level, rendezvous can bootstrap pubsub by discovering peers subscribed to a topic. The rendezvous would be responsible for publishing packets, subscribing, or unsubscribing from packet shapes. diff --git a/content/concepts/fundamentals/addressing.md b/content/concepts/fundamentals/addressing.md index d7ce517f..934f0551 100644 --- a/content/concepts/fundamentals/addressing.md +++ b/content/concepts/fundamentals/addressing.md @@ -14,19 +14,19 @@ A `multiaddress` (often abbreviated `multiaddr`), is a convention for encoding m For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their essential addressing information. The `/ip4/192.0.2.0` informs us that we want the `192.0.2.0` loopback address of the IPv4 protocol, and `/udp/1234` tells us we want to send UDP packets to port `1234`. -Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash](/concepts/appendix/glossary.md#multihash) of my IPFS node's public key. +Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash]({{< ref "/concepts/appendix/glossary.md#multihash" >}}) of my IPFS node's public key. {{< alert icon="💡" context="tip">}} -For more on peer identity and its relation to public key cryptography, see [Peer Identity](/concepts/fundamentals/peers.md#peer-id). +For more on peer identity and its relation to public key cryptography, see [Peer Identity]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}). {{< /alert >}} Let's say that I have the Peer ID `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` as above, and my public ip is `198.51.100.0`. I start my libp2p application and listen for connections on TCP port `4242`. -Now I can start [handing out multiaddrs to all my friends](/concepts/appendix/glossary.md#peer-routing), of the form `/ip4/198.51.100.0/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information. +Now I can start [handing out multiaddrs to all my friends]({{< ref "/concepts/appendix/glossary.md#peer-routing" >}}), of the form `/ip4/198.51.100.0/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information. Now not only do my friends know where to find me, anyone they give that address to can verify that the machine on the other side is really me, or at least, that they control the private key for my `PeerId`. They also know (by virtue of the `/p2p/` protocol id) that I'm likely to support common libp2p interactions like opening connections and negotiating what application protocols we can use to communicate. That's not bad! -This can be extended to account for multiple layers of addressing and abstraction. For example, the [addresses used for circuit relay](/concepts/nat/circuit-relay.md#relay-addresses) combine transport addresses with multiple peer identities to form an address that describes a "relay circuit": +This can be extended to account for multiple layers of addressing and abstraction. For example, the [addresses used for circuit relay]({{< ref "/concepts/nat/circuit-relay.md#relay-addresses" >}}) combine transport addresses with multiple peer identities to form an address that describes a "relay circuit": ```shell /ip4/198.51.100.0/tcp/4242/p2p/QmRelay/p2p-circuit/p2p/QmRelayedPeer diff --git a/content/concepts/fundamentals/peers.md b/content/concepts/fundamentals/peers.md index a157ead1..17009e79 100644 --- a/content/concepts/fundamentals/peers.md +++ b/content/concepts/fundamentals/peers.md @@ -25,7 +25,7 @@ peers. Every private key has a corresponding public key, which is shared with other peers. Together, the public and private key (or "key pair") allow peers to establish -[secure communication](/concepts/secure-comm/overview.md) channels with each other. +[secure communication]({{< ref "/concepts/secure-comm/overview.md" >}}) channels with each other. Conceptually, a Peer ID is a [cryptographic hash][wiki_hash_function] of a peer's public key. When peers establish a secure channel, the hash can be used to @@ -66,7 +66,7 @@ libp2p multiaddress for me would be: As with other multiaddrs, a `/p2p` address can be encapsulated into another multiaddr to compose into a new multiaddr. For example, I can combine -the above with a [transport](/concepts/transports/overview.md) address +the above with a [transport]({{< ref "/concepts/transports/overview.md" >}}) address `/ip4/198.51.100.0/tcp/4242` to produce this very useful address: ```shell @@ -78,7 +78,7 @@ transport. If some other peer has taken over that IP address or port, it will be immediately obvious, since they will not have control over the key pair used to produce the Peer ID embedded in the address. -**For more on addresses in libp2p, see [Addressing](/concepts/fundamentals/addressing.md)** +**For more on addresses in libp2p, see [Addressing]({{< ref "/concepts/fundamentals/addressing.md" >}})** {{< alert icon="💡" context="note">}} The multiaddr protocol for libp2p addresses was originally written `/ipfs` and was later renamed to `/p2p`. diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index 2940cccc..eee82399 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -11,7 +11,7 @@ There are protocols everywhere you look when you're writing network applications especially thick with them. The kind of protocols this article is concerned with are the ones built with libp2p itself, -using the core libp2p abstractions like [transport](/concepts/transports/overview.md), [peer identity](/concepts/fundamentals/peers.md#peer-id), [addressing](/concepts/fundamentals/addressing.md), and so on. +using the core libp2p abstractions like [transport]({{< ref "/concepts/transports/overview.md" >}}), [peer identity]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}), [addressing]({{< ref "/concepts/fundamentals/addressing.md" >}}), and so on. Throughout this article, we'll call this kind of protocol that is built with libp2p a **libp2p protocol**, but you may also see them referred to as "wire protocols" or "application protocols". @@ -65,8 +65,8 @@ properties: - Supports backpressure - Readers can't be flooded by eager writers -Behind the scenes, libp2p will also ensure that the stream is [secure](/concepts/secure-comm/overview.md) and efficiently -[multiplexed](/concepts/multiplex/overview.md). This is transparent to the protocol handler, which reads and writes +Behind the scenes, libp2p will also ensure that the stream is [secure]({{< ref "/concepts/secure-comm/overview.md" >}}) and efficiently +[multiplexed]({{< ref "/concepts/multiplex/overview.md" >}}). This is transparent to the protocol handler, which reads and writes unencrypted binary data over the stream. The format of the binary data and the mechanics of what to send when and by whom are all up to the protocol to determine. For inspiration, some [common patterns](#common-patterns) that are used in libp2p's internal protocols are outlined below. @@ -160,7 +160,7 @@ The basic identify protocol works by establishing a new stream to a peer using t shown in the table above. When the remote peer opens the new stream, they will fill out an [`Identify` protobuf message][identify_proto] containing -information about themselves, such as their public key, which is used to derive their [`PeerId`](/concepts/fundamentals/peers.md). +information about themselves, such as their public key, which is used to derive their [`PeerId`]({{< ref "/concepts/fundamentals/peers.md" >}}). Importantly, the `Identify` message includes an `observedAddr` field that contains the [multiaddr][definition_multiaddr] that the peer observed the request coming in on. This helps peers determine their NAT status, since it allows them to @@ -177,7 +177,7 @@ see what other peers observe as their public address and compare it to their own A slight variation on `identify`, the `identify/push` protocol sends the same `Identify` message, but it does so proactively instead of in response to a request. -This is useful if a peer starts listening on a new address, establishes a new [relay circuit](/concepts/nat/circuit-relay.md), or +This is useful if a peer starts listening on a new address, establishes a new [relay circuit]({{< ref "/concepts/nat/circuit-relay.md" >}}), or learns of its public address from other peers using the standard `identify` protocol. Upon creating or learning of a new address, the peer can push the new address to all peers it's currently aware of. This keeps everyone's routing tables up to date and makes it more likely that other peers will discover the new address. @@ -186,7 +186,7 @@ makes it more likely that other peers will discover the new address. `kad-dht` is a [Distributed Hash Table][wiki_dht] based on the [Kademlia][wiki_kad] routing algorithm, with some modifications. -libp2p uses the DHT as the foundation of its [routing](/concepts/discovery-routing/overview.md) functionality. To learn more about DHT and the Kademlia algorithm, +libp2p uses the DHT as the foundation of its [routing]({{< ref "/concepts/discovery-routing/overview.md" >}}) functionality. To learn more about DHT and the Kademlia algorithm, check out the [Distributed Hash Tables guide][dht] on the IPFS documentation site. In addition, check out the [libp2p implementations page](https://libp2p.io/implementations/) for updates on all the kad-libp2p implementations. @@ -205,7 +205,7 @@ check out the [Distributed Hash Tables guide][dht] on the IPFS documentation sit [relay_js]: https://github.com/libp2p/js-libp2p-circuit [relay_go]: https://github.com/libp2p/go-libp2p-circuit -As described in the [Circuit Relay article](/concepts/nat/circuit-relay.md), libp2p provides a protocol +As described in the [Circuit Relay article]({{< ref "/concepts/nat/circuit-relay.md" >}}), libp2p provides a protocol for tunneling traffic through relay peers when two peers are unable to connect to each other directly. See the article for more information on working with relays, including notes on relay addresses and how to enable automatic relay connection when behind an intractable NAT. diff --git a/content/concepts/introduction/overview.md b/content/concepts/introduction/overview.md index 915ba8f2..8e37ce28 100644 --- a/content/concepts/introduction/overview.md +++ b/content/concepts/introduction/overview.md @@ -22,7 +22,7 @@ has something for you. {{< alert icon="" context="">}} If you have any questions or suggestions as you navigate the documentation, -please don't hesitate to [reach out](/concepts/contribute/community.md), or help +please don't hesitate to [reach out]({{< ref "/concepts/contribute/community.md" >}}), or help improve the documentation by [contributing to the site](https://github.com/libp2p/docs). {{< /alert >}} @@ -36,7 +36,7 @@ libp2p, (short for "library peer-to-peer") is a peer-to-peer (P2P) networking framework that enables the development of P2P applications. It consists of a collection of protocols, specifications, and libraries that facilitate P2P communication between network participants, known as -"[peers](/concepts/fundamentals/peers.md)." +"[peers]({{< ref "/concepts/fundamentals/peers.md" >}})." ### Peer-to-peer basics @@ -85,7 +85,7 @@ There are several reasons to consider using libp2p as a networking layer to crea to fit the specific requirements of any P2P application. - **Extensive transport configurability**: libp2p provides a set of specifications that can be adapted to - support various [transport protocols](/concepts/transports/overview.md), allowing libp2p applications to operate + support various [transport protocols]({{< ref "/concepts/transports/overview.md" >}}), allowing libp2p applications to operate in various runtime and networking environments as the wealth of transport protocol choices makes it possible to use libp2p in a variety of scenarios. @@ -94,19 +94,19 @@ There are several reasons to consider using libp2p as a networking layer to crea [implemented in many programming languages](https://libp2p.io/implementations/), providing developers with great flexibility when building P2P applications. -- **Security**: libp2p includes [several security features](/concepts/security/security-considerations.md), +- **Security**: libp2p includes [several security features]({{< ref "/concepts/security/security-considerations.md" >}}), such as peer identity verification using public key cryptography and - [encrypted communication](/concepts/secure-comm/overview.md) between peers using modern cryptographic algorithms. + [encrypted communication]({{< ref "/concepts/secure-comm/overview.md" >}}) between peers using modern cryptographic algorithms. - **Robustness**: libp2p is a robust and reliable networking protocol that is designed to withstand stress, disturbance, and change. Its features and design choices ensure that it is able to function effectively and efficiently in a wide range of environments, and it is able to recover quickly from disruptions or failures. It also offers protection against network attacks through the use of - [mitigation techniques](/concepts/security/dos-mitigation.md). + [mitigation techniques]({{< ref "/concepts/security/dos-mitigation.md" >}}). - **Resiliency**: P2P networks are often more resilient than traditional client-server networks, as there is no single point of failure. libp2p includes features such as - [peer discovery and content routing](/concepts/discovery-routing/overview.md) that help + [peer discovery and content routing]({{< ref "/concepts/discovery-routing/overview.md" >}}) that help to ensure that the network remains available and accessible even if some peers are offline or unreachable. - **Efficiency**: P2P networks can be more efficient in resource utilization, as data is @@ -114,15 +114,15 @@ There are several reasons to consider using libp2p as a networking layer to crea and retrieval patterns that allow developers to distribute data efficiently across the network, making it possible to store and retrieve data in a cost-effective and scalable way. -- **Piercing NAT Barriers**: libp2p is equipped with capabilities for [NAT traversal](/concepts/nat/overview.md), +- **Piercing NAT Barriers**: libp2p is equipped with capabilities for [NAT traversal]({{< ref "/concepts/nat/overview.md" >}}), which allows P2P communication between peers even when they are behind NAT devices or firewalls. This helps to maintain the connectivity of the network and ensure that it remains accessible despite the presence of these obstacles. - **Message Distribution and Dissemination**: One such pattern libp2p uses is - [publish/subscribe (pubsub)](/concepts/pubsub/overview.md), which allows a sender (publisher) to send a message + [publish/subscribe (pubsub)]({{< ref "/concepts/pubsub/overview.md" >}}), which allows a sender (publisher) to send a message to multiple recipients (subscribers) without the publisher having to know who the subscribers are. - libp2p implements pubsub through the use of protocols like [gossipsub](/concepts/pubsub/overview.md#gossip), providing + libp2p implements pubsub through the use of protocols like [gossipsub]({{< ref "/concepts/pubsub/overview.md#gossip" >}}), providing developers with a flexible and efficient means of exchanging data and messages within their P2P applications. diff --git a/content/concepts/multiplex/early-negotiation.md b/content/concepts/multiplex/early-negotiation.md index c4da7718..01871880 100644 --- a/content/concepts/multiplex/early-negotiation.md +++ b/content/concepts/multiplex/early-negotiation.md @@ -21,9 +21,9 @@ second [is shown in a diagram here](https://github.com/libp2p/specs/tree/master/connections#upgrading-connections). First, the security protocol is negotiated, then this protocol is used to perform a cryptographic -handshake. libp2p currently supports [Noise](/concepts/secure-comm/noise.md) and [TLS 1.3](/concepts/secure-comm/tls.md). +handshake. libp2p currently supports [Noise]({{< ref "/concepts/secure-comm/noise.md" >}}) and [TLS 1.3]({{< ref "/concepts/secure-comm/tls.md" >}}). Once the cryptographic handshake completes, multistream-select runs again on top of -the secured connection to negotiate a steam multiplexer, like [yamux](/concepts/multiplex/yamux.md) or [mplex](/concepts/multiplex/mplex.md). +the secured connection to negotiate a steam multiplexer, like [yamux]({{< ref "/concepts/multiplex/yamux.md" >}}) or [mplex]({{< ref "/concepts/multiplex/mplex.md" >}}). diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index b0c4d709..8affc505 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -13,7 +13,7 @@ is now considered critical for a stream multiplexer. mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection. Peers can open, write to, close, and reset a stream. mplex uses a message-based framing -layer like [yamux](/concepts/multiplex/yamux.md), enabling it to multiplex different +layer like [yamux]({{< ref "/concepts/multiplex/yamux.md" >}}), enabling it to multiplex different data streams, including stream-oriented data and other types of messages. ### Drawbacks diff --git a/content/concepts/multiplex/overview.md b/content/concepts/multiplex/overview.md index df4ec9fd..9e224c1c 100644 --- a/content/concepts/multiplex/overview.md +++ b/content/concepts/multiplex/overview.md @@ -51,10 +51,10 @@ and allowing for the seamless transmission of multiple streams of data over a si connection. {{< /alert >}} -Currently, libp2p supports two stream muxers, [mplex](/concepts/multiplex/mplex.md) -and [yamux](/concepts/multiplex/yamux.md). However, many of the -[transport protocols](/concepts/transports/overview.md) available in the libp2p stack -come with native streams, such as [QUIC](/concepts/transports/quic.md), -[WebTransport](/concepts/transports/webtransport.md), and -[WebRTC](/concepts/transports/webrtc.md), and in these cases, libp2p +Currently, libp2p supports two stream muxers, [mplex]({{< ref "/concepts/multiplex/mplex.md" >}}) +and [yamux]({{< ref "/concepts/multiplex/yamux.md" >}}). However, many of the +[transport protocols]({{< ref "/concepts/transports/overview.md" >}}) available in the libp2p stack +come with native streams, such as [QUIC]({{< ref "/concepts/transports/quic.md" >}}), +[WebTransport]({{< ref "/concepts/transports/webtransport.md" >}}), and +[WebRTC]({{< ref "/concepts/transports/webrtc.md" >}}), and in these cases, libp2p **does not need to perform stream multiplexing** as the protocol already provides it. diff --git a/content/concepts/multiplex/switch.md b/content/concepts/multiplex/switch.md index 7f98707c..abce4e03 100644 --- a/content/concepts/multiplex/switch.md +++ b/content/concepts/multiplex/switch.md @@ -9,4 +9,4 @@ libp2p maintains some state about known peers and existing connections in a comp When configuring libp2p, applications enable stream muxing modules, which the switch will use when dialing peers and listening for connections. If the remote peers support any of the same stream muxing implementations, the switch will select and use it when establishing the connection. If you dial a peer that the switch already has an open connection to, the new stream will automatically be multiplexed over the existing connection. -Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation](/concepts/fundamentals/protocols.md#protocol-negotiation) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams. +Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams. diff --git a/content/concepts/nat/autonat.md b/content/concepts/nat/autonat.md index fa79a905..8107a61f 100644 --- a/content/concepts/nat/autonat.md +++ b/content/concepts/nat/autonat.md @@ -65,7 +65,7 @@ whether or not it is behind a NAT. > If the response indicates success, the node is likely not behind a NAT and does > not need to use a relay server to improve its connectivity. If the response indicates > an error, the node is likely behind a NAT and may need to use a -> [relay server](/concepts/nat/dcutr.md) to communicate with other nodes in the network. +> [relay server]({{< ref "/concepts/nat/dcutr.md" >}}) to communicate with other nodes in the network. {{< alert icon="" context="caution">}} To prevent diff --git a/content/concepts/nat/circuit-relay.md b/content/concepts/nat/circuit-relay.md index ae1d2ae5..95f5d293 100644 --- a/content/concepts/nat/circuit-relay.md +++ b/content/concepts/nat/circuit-relay.md @@ -9,9 +9,9 @@ aliases: ## What is Circuit Relay? -Circuit relay is a [transport protocol](/concepts/transports/overview.md) that routes traffic between two peers over a third-party "relay" peer. +Circuit relay is a [transport protocol]({{< ref "/concepts/transports/overview.md" >}}) that routes traffic between two peers over a third-party "relay" peer. -In many cases, peers will be unable to [traverse their NAT and/or firewall](/concepts/nat/overview.md) in a way that makes them publicly accessible. Or they may not share common [transport protocols](/concepts/transports/overview.md) that would allow them to communicate directly. +In many cases, peers will be unable to [traverse their NAT and/or firewall]({{< ref "/concepts/nat/overview.md" >}}) in a way that makes them publicly accessible. Or they may not share common [transport protocols]({{< ref "/concepts/transports/overview.md" >}}) 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]. When a peer isn't able to listen on a public address, it can dial out to a relay peer, which will keep a long-lived connection open. Other peers will be able to dial through the relay peer using a `p2p-circuit` address, which will forward traffic to its destination. @@ -30,7 +30,7 @@ Today there are two versions of the circuit relay protocol, [v1](https://github. ## Relay addresses -A relay circuit is identified using a [multiaddr][definition_muiltiaddress] that includes the [Peer ID](/concepts/fundamentals/peers.md#peer-id) of the peer whose traffic is being relayed (the listening peer or "relay target"). +A relay circuit is identified using a [multiaddr][definition_multiaddress] that includes the [Peer ID]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer whose traffic is being relayed (the listening peer or "relay target"). Let's say that I have a peer with the Peer ID `QmAlice`. I want to give out my address to my friend `QmBob`, but I'm behind a NAT that won't let anyone dial me directly. @@ -38,7 +38,7 @@ The most basic `p2p-circuit` address I can construct looks like this: `/p2p-circuit/p2p/QmAlice` -The address above is interesting, because it doesn't include any [transport](/concepts/transports/overview.md) addresses for either the peer we want to contact (`QmAlice`) or for the relay peer that will convey the traffic. Without that information, the only chance a peer has of dialing me is to discover a relay and hope they have a connection to me. +The address above is interesting, because it doesn't include any [transport]({{< ref "/concepts/transports/overview.md" >}}) addresses for either the peer we want to contact (`QmAlice`) or for the relay peer that will convey the traffic. Without that information, the only chance a peer has of dialing me is to discover a relay and hope they have a connection to me. A better address would be something like `/p2p/QmRelay/p2p-circuit/p2p/QmAlice`. This includes the identity of a specific relay peer, `QmRelay`. If a peer already knows how to open a connection to `QmRelay`, they'll be able to reach us. @@ -60,10 +60,10 @@ The below sequence diagram depicts a sample relay process: ![Circuit v2 Protocol Interaction](https://raw.githubusercontent.com/libp2p/specs/master/relay/circuit-v2.svg) -1. Node `A` is behind a NAT and/or firewall, e.g. detected via the [AutoNAT service](/concepts/nat/autonat.md). +1. Node `A` is behind a NAT and/or firewall, e.g. detected via the [AutoNAT service]({{< ref "/concepts/nat/autonat.md" >}}). 2. Node `A` therefore requests a reservation with relay `R`. I.e. node `A` asks relay `R` to listen for incoming connections on its behalf. 3. Node `B` wants to establish a connection to node `A`. Given that node `A` does not advertise any direct addresses but only a relay address, node `B` connects to relay `R`, asking relay `R` to relay a connection to `A`. 4. Relay `R` forwards the connection request to node `A` and eventually relays all data send by `A` and `B`. [spec_relay]: https://github.com/libp2p/specs/tree/master/relay -[definition_muiltiaddress]: /concepts/appendix/glossary.md#multiaddr +[definition_multiaddress]: /concepts/appendix/glossary.md#multiaddr diff --git a/content/concepts/nat/dcutr.md b/content/concepts/nat/dcutr.md index 2cf11dd0..df7d1ba0 100644 --- a/content/concepts/nat/dcutr.md +++ b/content/concepts/nat/dcutr.md @@ -8,7 +8,7 @@ weight: 210 Relays are used to traverse NATs by acting as proxies, but this can be expensive to scale and maintain, and may result in low-bandwidth, high-latency -connections. [Hole punching](/concepts/nat/hole-punching.md) is another technique +connections. [Hole punching]({{< ref "/concepts/nat/hole-punching.md" >}}) is another technique that enables NAT traversal by enabling two nodes behind NATs to communicate directly. However, in addition to relay nodes, it requires another piece of infrastructure called signaling servers. @@ -35,7 +35,7 @@ The DCUtR protocol uses the protocol ID `/libp2p/dcutr` and involves the exchange of `Connect` and `Sync` messages. The DCUtR protocol supports different types of connections, such as TCP and -[QUIC](/concepts/transports/quic.md), the process of establishing a connection is +[QUIC]({{< ref "/concepts/transports/quic.md" >}}), the process of establishing a connection is different for each type. @Dennis-tra has a [great talk](https://www.youtube.com/watch?v=fyhZWlDbcyM) on diff --git a/content/concepts/nat/hole-punching.md b/content/concepts/nat/hole-punching.md index a536a6e5..8ac4dc1a 100644 --- a/content/concepts/nat/hole-punching.md +++ b/content/concepts/nat/hole-punching.md @@ -97,7 +97,7 @@ a hole punching phase. ### Phase I: Preparation -1. [AutoNAT](/concepts/nat/autonat.md): Determine whether a node is dialable, +1. [AutoNAT]({{< ref "/concepts/nat/autonat.md" >}}): Determine whether a node is dialable, as in, discover if a node is behind a NAT or firewall. > This is equivalent to the @@ -131,7 +131,7 @@ a hole punching phase. for the closest peers to its Peer ID or choose a subset of the public nodes it is already connected to. -2. [Circuit Relay](/concepts/nat/circuit-relay.md): Connect to and request +2. [Circuit Relay]({{< ref "/concepts/nat/circuit-relay.md" >}}): Connect to and request reservations with the discovered relay nodes. A node can advertise itself as being reachable through a remote relay node. @@ -152,7 +152,7 @@ a hole punching phase. ### Phase II: Hole punching -1. [Circuit Relay](/concepts/nat/circuit-relay.md): Establish a secure relay connection +1. [Circuit Relay]({{< ref "/concepts/nat/circuit-relay.md" >}}): Establish a secure relay connection through the public relay node. Node `A` establishes a direct connection with the relay node. Node `B` then requests a relayed connection to node `A` through the relay node, creating a bi-directional channel and uses TLS to secure the diff --git a/content/concepts/nat/overview.md b/content/concepts/nat/overview.md index 01a88e7c..f1142210 100644 --- a/content/concepts/nat/overview.md +++ b/content/concepts/nat/overview.md @@ -8,7 +8,7 @@ aliases: ## Overview -The internet is composed of countless networks, bound together into shared address spaces by foundational [transport protocols](/concepts/transports/overview.md). +The internet is composed of countless networks, bound together into shared address spaces by foundational [transport protocols]({{< ref "/concepts/transports/overview.md" >}}). As traffic moves between network boundaries, it's very common for a process called Network Address Translation to occur. Network Address Translation (NAT) maps an address from one address space to another. diff --git a/content/concepts/secure-comm/overview.md b/content/concepts/secure-comm/overview.md index 283fc1e5..b80ba4c1 100644 --- a/content/concepts/secure-comm/overview.md +++ b/content/concepts/secure-comm/overview.md @@ -12,12 +12,12 @@ Before two peers can transmit data, the communication channel they establish needs to be secured. By design, libp2p supports many different transports (TCP, QUIC, WebSocket, WebTransport, etc.). Some transports have built-in encryption at the transport layer -like [QUIC](/concepts/transports/quic.md), while other transports (e.g. TCP, WebSocket) +like [QUIC]({{< ref "/concepts/transports/quic.md" >}}), while other transports (e.g. TCP, WebSocket) lack native security and require a security handshake after the transport connection has been established. ## Secure channels in libp2p -libp2p specifies two security protocols, [TLS 1.3](/concepts/secure-comm/tls.md) and [Noise](/concepts/secure-comm/noise.md). +libp2p specifies two security protocols, [TLS 1.3]({{< ref "/concepts/secure-comm/tls.md" >}}) and [Noise]({{< ref "/concepts/secure-comm/noise.md" >}}). After the handshake has finished, we need to negotiate a -[stream multiplexer](/concepts/multiplex/overview.md) for the connection. +[stream multiplexer]({{< ref "/concepts/multiplex/overview.md" >}}) for the connection. diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 71a0d594..97afd143 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -7,7 +7,7 @@ aliases: --- TLS (Transport Layer Security) is one of the security handshakes used to secure transports -that don't have built-in security (e.g. TCP, WebSocket). [Noise](/concepts/secure-comm/noise.md), an alternative to +that don't have built-in security (e.g. TCP, WebSocket). [Noise]({{< ref "/concepts/secure-comm/noise.md" >}}), an alternative to TLS, is also another security handshake used to secure transports. ## What is TLS? diff --git a/content/concepts/security/dos-mitigation.md b/content/concepts/security/dos-mitigation.md index 0f7e514f..8fdc383f 100644 --- a/content/concepts/security/dos-mitigation.md +++ b/content/concepts/security/dos-mitigation.md @@ -355,11 +355,11 @@ RestartSec=1min User=ipfs ``` -#### Example screen recording of fail2ban in action + -[fail2ban+go-libp2p screen recording](/images/fail2bango-libp2p.mp4) + #### Setting Up fail2ban diff --git a/content/concepts/security/security-considerations.md b/content/concepts/security/security-considerations.md index 4c0642e9..071c7b68 100644 --- a/content/concepts/security/security-considerations.md +++ b/content/concepts/security/security-considerations.md @@ -29,7 +29,7 @@ reasonably succeed. ## Identity and Trust -Every libp2p peer is uniquely identified by their [Peer ID](/concepts/fundamentals/peers.md#peer-id), which +Every libp2p peer is uniquely identified by their [Peer ID]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}), which is derived from a private cryptographic key. Peer ids and their corresponding keys allow us to _authenticate_ remote peers, so that we can be sure we're talking to the correct peer and not an imposter. @@ -48,7 +48,7 @@ To design an authorization system on libp2p, you can rely on the authentication of peer ids and build an association between peer ids and permissions, with the Peer ID serving the same function as the "username" in traditional authorization frameworks, and the peer's private key serving as the "password". -Your [protocol handler](/concepts/fundamentals/protocols.md/#handler-functions) could then +Your [protocol handler]({{< ref "/concepts/fundamentals/protocols.md#handler-functions" >}}) could then reject requests from untrusted peers. Of course, it's also possible to build other kinds of authorization systems on @@ -141,7 +141,7 @@ returning dishonest routing information. ### Publish / Subscribe -libp2p's [publish/subscribe protocol](/concepts/pubsub/overview.md) allows a peer +libp2p's [publish/subscribe protocol]({{< ref "/concepts/pubsub/overview.md" >}}) allows a peer to broadcast messages to other peers within a given "topic." By default, the `gossipsub` implementation will sign all messages with the diff --git a/content/concepts/transports/listen-and-dial.md b/content/concepts/transports/listen-and-dial.md index e2c0f57c..1aa3cc10 100644 --- a/content/concepts/transports/listen-and-dial.md +++ b/content/concepts/transports/listen-and-dial.md @@ -28,7 +28,7 @@ reach them. Because each transport will likely require its own address scheme, libp2p uses a convention called a "multiaddress" or `multiaddr` to encode many different addressing schemes. -The [addressing doc](/concepts/fundamentals/addressing.md) goes into more detail, but an overview +The [addressing doc]({{< ref "/concepts/fundamentals/addressing.md" >}}) goes into more detail, but an overview of how multiaddresses work is helpful for understanding the dial and listen interfaces. @@ -43,15 +43,15 @@ has the advantage of being explicit about the protocols that are being described. With the multiaddr, you can see at a glance that the `198.51.100.0` address belongs to the IPv4 protocol, and the `6543` belongs to TCP. -For more complex examples, see [addressing](/concepts/fundamentals/addressing.md). +For more complex examples, see [addressing]({{< ref "/concepts/fundamentals/addressing.md" >}}). Both dial and listen deal with multiaddresses. When listening, you give the transport the address you'd like to listen on, and when dialing you provide the address to dial to. When dialing a remote peer, the multiaddress should include the -[PeerId](/concepts/fundamentals/peers.md#peer-id) of the peer you're trying to reach. -This lets libp2p establish a [secure communication channel](/concepts/secure-comm/overview.md) +[PeerId]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer you're trying to reach. +This lets libp2p establish a [secure communication channel]({{< ref "/concepts/secure-comm/overview.md" >}}) and prevents impersonation. An example multiaddress that includes a `PeerId`: @@ -62,7 +62,7 @@ An example multiaddress that includes a `PeerId`: The `/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6` component uniquely identifies the remote peer using the hash of its public key. -For more, see the [peer identity content](/concepts/fundamentals/peers.md#peer-id). +For more, see the [peer identity content]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}). {{< alert icon="💡" context="tip">}} When peer routing is enabled, you can dial peers using just their PeerId, @@ -78,9 +78,9 @@ in a web browser. The libp2p component responsible for managing the transports is called the [switch][definition_switch], which also coordinates -[protocol negotiation](/concepts/fundamentals/protocols.md#protocol-negotiation), -[stream multiplexing](/concepts/multiplex/overview.md), -[establishing secure communication](/concepts/secure-comm/overview.md) and other forms of +[protocol negotiation]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}), +[stream multiplexing]({{< ref "/concepts/multiplex/overview.md" >}}), +[establishing secure communication]({{< ref "/concepts/secure-comm/overview.md" >}}) and other forms of "connection upgrading". The switch provides a single "entry point" for dialing and listening, and frees diff --git a/content/concepts/transports/quic.md b/content/concepts/transports/quic.md index 8cc37e44..09ef9f69 100644 --- a/content/concepts/transports/quic.md +++ b/content/concepts/transports/quic.md @@ -85,7 +85,7 @@ when it has already communicated with a certain server. The client can then send ### QUIC native multiplexing A single QUIC packet can carry frames containing stream data from one or more -streams. Since QUIC packets can be decrypted even when they're received out of order, this solves the problem of [HoL blocking](/#key-challenges-with-tcp) that multiplexers applied on top of a TCP connection suffer from: If a packet that contains +streams. Since QUIC packets can be decrypted even when they're received out of order, this solves the problem of [HoL blocking](#key-challenges-with-tcp) that multiplexers applied on top of a TCP connection suffer from: If a packet that contains stream data for one stream is lost, this only blocks progress on this one stream. All other streams can still make progress. diff --git a/content/concepts/transports/webrtc.md b/content/concepts/transports/webrtc.md index 7fbff3be..286ed317 100644 --- a/content/concepts/transports/webrtc.md +++ b/content/concepts/transports/webrtc.md @@ -42,7 +42,7 @@ The features employed in libp2p are: to a peer. This means libp2p can utilize data channels as a transport to send raw data to peers and enables applications to build anything they like. -- [NAT traversal](/concepts/nat/overview.md): WebRTC includes mechanisms (like +- [NAT traversal]({{< ref "/concepts/nat/overview.md" >}}): WebRTC includes mechanisms (like [ICE](https://datatracker.ietf.org/doc/rfc5245/)) to connect to nodes that run behind NATs and firewalls. In non-decentralized WebRTC, this can be facilitated by a [TURN server.](https://webrtc.org/getting-started/turn-server), @@ -97,7 +97,7 @@ When establishing a WebRTC connection, the browser and server perform a standard handshake as part of the connection setup. Of the three primary focuses of information security, a successful DTLS handshake only provides two: confidentiality and integrity. Authenticity is achieved by succeeding the -[Noise handshake](/concepts/secure-comm/noise.md) following the DTLS handshake. +[Noise handshake]({{< ref "/concepts/secure-comm/noise.md" >}}) following the DTLS handshake. From 21f276e297886a9f4d50751185e7f09565bc9249 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Mon, 7 Aug 2023 19:31:39 -0400 Subject: [PATCH 11/17] Remove base from link checker --- .github/workflows/link-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 28f87f1c..37c55487 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -17,7 +17,7 @@ jobs: with: # Check all markdown in /content/ # Ignore twitter.com links because they all 503 unless logged in - args: --no-progress --base ./content --exclude twitter.com ./content + args: --no-progress --exclude twitter.com ./content fail: true env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} From a37ec6e66c64a90c1e1d6caef43f7319e07cd8eb Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Mon, 7 Aug 2023 19:40:13 -0400 Subject: [PATCH 12/17] Trigger rebuild of dos-mitigation.md --- content/concepts/security/dos-mitigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/security/dos-mitigation.md b/content/concepts/security/dos-mitigation.md index 8fdc383f..a69e95da 100644 --- a/content/concepts/security/dos-mitigation.md +++ b/content/concepts/security/dos-mitigation.md @@ -356,7 +356,7 @@ User=ipfs ``` - + From 305863b214e651a4aa2753385ca352a904ba04c7 Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Mon, 7 Aug 2023 19:43:38 -0400 Subject: [PATCH 13/17] Mangle commented out dead link --- content/concepts/security/dos-mitigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/security/dos-mitigation.md b/content/concepts/security/dos-mitigation.md index a69e95da..7daa6cdb 100644 --- a/content/concepts/security/dos-mitigation.md +++ b/content/concepts/security/dos-mitigation.md @@ -359,7 +359,7 @@ User=ipfs - + #### Setting Up fail2ban From 549f9c2058a0eeb4f6fdc3fe91fe60472545b7fc Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Tue, 8 Aug 2023 13:25:19 -0400 Subject: [PATCH 14/17] Remove .md from glossary links --- content/concepts/fundamentals/peers.md | 4 ++-- content/concepts/fundamentals/protocols.md | 4 ++-- content/concepts/nat/circuit-relay.md | 2 +- content/concepts/security/security-considerations.md | 2 +- content/concepts/transports/listen-and-dial.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/concepts/fundamentals/peers.md b/content/concepts/fundamentals/peers.md index 17009e79..9e33bfbf 100644 --- a/content/concepts/fundamentals/peers.md +++ b/content/concepts/fundamentals/peers.md @@ -119,8 +119,8 @@ un-{known, identified} peers on the peer routing guide. [wiki_hash_function]: https://en.wikipedia.org/wiki/Cryptographic_hash_function [wiki_base58]: https://en.wikipedia.org/wiki/Base58 -[definition_multiaddr]: /concepts/appendix/glossary.md#multiaddr -[definition_multihash]: /concepts/appendix/glossary.md#multihash +[definition_multiaddr]: /concepts/appendix/glossary#multiaddr +[definition_multihash]: /concepts/appendix/glossary#multihash [spec_peerid]: https://github.com/libp2p/specs/blob/master/peer-ids/peer-ids.md [identity]: https://github.com/libp2p/specs/blob/master/identify/README.md#identifypush diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index eee82399..ef8e6f40 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -210,5 +210,5 @@ for tunneling traffic through relay peers when two peers are unable to connect t directly. See the article for more information on working with relays, including notes on relay addresses and how to enable automatic relay connection when behind an intractable NAT. -[definition_switch]: /concepts/appendix/glossary.md#switch -[definition_multiaddr]: /concepts/appendix/glossary.md#multiaddr +[definition_switch]: /concepts/appendix/glossary#switch +[definition_multiaddr]: /concepts/appendix/glossary#multiaddr diff --git a/content/concepts/nat/circuit-relay.md b/content/concepts/nat/circuit-relay.md index 95f5d293..f6a49166 100644 --- a/content/concepts/nat/circuit-relay.md +++ b/content/concepts/nat/circuit-relay.md @@ -66,4 +66,4 @@ The below sequence diagram depicts a sample relay process: 4. Relay `R` forwards the connection request to node `A` and eventually relays all data send by `A` and `B`. [spec_relay]: https://github.com/libp2p/specs/tree/master/relay -[definition_multiaddress]: /concepts/appendix/glossary.md#multiaddr +[definition_multiaddress]: /concepts/appendix/glossary#multiaddr diff --git a/content/concepts/security/security-considerations.md b/content/concepts/security/security-considerations.md index 071c7b68..223374c4 100644 --- a/content/concepts/security/security-considerations.md +++ b/content/concepts/security/security-considerations.md @@ -159,6 +159,6 @@ attacks. We expect this to lead to a more robust and attack-resistant pubsub protocol, but it is unlikely to prevent all classes of possible attack by determined bad actors. -[glossary-dht]: /concepts/appendix/glossary.md#dht +[glossary-dht]: /concepts/appendix/glossary#dht [wikipedia-sybil]: https://en.wikipedia.org/wiki/Sybil_attack [paper-s-kademlia]: https://telematics.tm.kit.edu/publications/Files/267/SKademlia_2007.pdf diff --git a/content/concepts/transports/listen-and-dial.md b/content/concepts/transports/listen-and-dial.md index 1aa3cc10..3998d3cd 100644 --- a/content/concepts/transports/listen-and-dial.md +++ b/content/concepts/transports/listen-and-dial.md @@ -89,4 +89,4 @@ and other pieces of the "connection stack" that are used under the hood. {{< alert icon="💡" context="note" text="The term \"swarm\" was previously used to refer to what is now called the \"switch\", and some places in the codebase still use the \"swarm\" terminology." />}} -[definition_switch]: /concepts/appendix/glossary.md#switch +[definition_switch]: /concepts/appendix/glossary#switch From fbc2a4b59094a71a43844f8b082932edc859186b Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Fri, 11 Aug 2023 14:31:18 -0400 Subject: [PATCH 15/17] Use relref instead of ref --- content/concepts/appendix/glossary.md | 8 ++++---- .../concepts/discovery-routing/overview.md | 8 ++++---- .../concepts/discovery-routing/rendezvous.md | 6 +++--- content/concepts/fundamentals/addressing.md | 8 ++++---- content/concepts/fundamentals/peers.md | 6 +++--- content/concepts/fundamentals/protocols.md | 14 ++++++------- content/concepts/introduction/overview.md | 20 +++++++++---------- .../concepts/multiplex/early-negotiation.md | 4 ++-- content/concepts/multiplex/mplex.md | 2 +- content/concepts/multiplex/overview.md | 12 +++++------ content/concepts/multiplex/switch.md | 2 +- content/concepts/nat/autonat.md | 2 +- content/concepts/nat/circuit-relay.md | 12 +++++------ content/concepts/nat/dcutr.md | 4 ++-- content/concepts/nat/hole-punching.md | 6 +++--- content/concepts/nat/overview.md | 2 +- content/concepts/secure-comm/overview.md | 6 +++--- content/concepts/secure-comm/tls.md | 2 +- .../security/security-considerations.md | 8 ++++---- .../concepts/transports/listen-and-dial.md | 18 ++++++++--------- content/concepts/transports/webrtc.md | 4 ++-- 21 files changed, 77 insertions(+), 77 deletions(-) diff --git a/content/concepts/appendix/glossary.md b/content/concepts/appendix/glossary.md index 454bb396..6d51a1f9 100644 --- a/content/concepts/appendix/glossary.md +++ b/content/concepts/appendix/glossary.md @@ -61,7 +61,7 @@ For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their es Multiaddresses can be composed to describe multiple "layers" of addresses. -For more detail, see [Addressing]({{< ref "/concepts/fundamentals/addressing.md" >}}), or the [multiaddr spec](https://github.com/multiformats/multiaddr), which has links to many implementations. +For more detail, see [Addressing]({{< relref "/concepts/fundamentals/addressing.md" >}}), or the [multiaddr spec](https://github.com/multiformats/multiaddr), which has links to many implementations. ### Multiaddress @@ -205,7 +205,7 @@ agree upon what protocols to use. The implementation of the libp2p handshake is called [multistream-select](https://github.com/multiformats/multistream-select). -For details, see the [protocol negotiation article]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}). +For details, see the [protocol negotiation article]({{< relref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}). ### Stream @@ -231,9 +231,9 @@ without having to specify what transport to use. In addition to managing transports, the switch also coordinates the "connection upgrade" process, which promotes a "raw" connection from the transport layer into one that supports -[protocol negotiation]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}), +[protocol negotiation]({{< relref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}), [stream multiplexing](#multiplexing), and -[secure communications]({{< ref "/concepts/secure-comm/overview.md" >}}). +[secure communications]({{< relref "/concepts/secure-comm/overview.md" >}}). Sometimes called ["swarm"](#swarm) for historical reasons. diff --git a/content/concepts/discovery-routing/overview.md b/content/concepts/discovery-routing/overview.md index a9a4ec9d..2887284d 100644 --- a/content/concepts/discovery-routing/overview.md +++ b/content/concepts/discovery-routing/overview.md @@ -40,16 +40,16 @@ implementation, discovery and routing usually happen concurrently. libp2p provides a set of modules for different network-level functionality, including peer discovery and routing. Peers in libp2p can discover other peers using various mechanisms, such as exchanging peer -[multiaddresses]({{< ref "/concepts/fundamentals/addressing.md" >}}) over the +[multiaddresses]({{< relref "/concepts/fundamentals/addressing.md" >}}) over the network, querying a directory service, or using a distributed hash table (DHT) to store and retrieve information about available peers. These methods include, but are not limited to: -- [Rendezvous]({{< ref "/concepts/discovery-routing/rendezvous.md" >}}): a protocol that allows peers to exchange peer multiaddresses +- [Rendezvous]({{< relref "/concepts/discovery-routing/rendezvous.md" >}}): a protocol that allows peers to exchange peer multiaddresses in a secure and private manner. -- [mDNS]({{< ref "/concepts/discovery-routing/mDNS.md" >}}): a multicast Domain Name System (DNS) protocol that allows peers to +- [mDNS]({{< relref "/concepts/discovery-routing/mDNS.md" >}}): a multicast Domain Name System (DNS) protocol that allows peers to discover other peers on the local network. -- [DHT]({{< ref "/concepts/discovery-routing/kaddht.md" >}}): Distributed Hash Table, libp2p uses a DHT called Kademlia, it assigns +- [DHT]({{< relref "/concepts/discovery-routing/kaddht.md" >}}): Distributed Hash Table, libp2p uses a DHT called Kademlia, it assigns each piece of content a unique identifier and stores the content on the peer whose identifier is closest to the content's identifier. diff --git a/content/concepts/discovery-routing/rendezvous.md b/content/concepts/discovery-routing/rendezvous.md index a010326a..3779e88d 100644 --- a/content/concepts/discovery-routing/rendezvous.md +++ b/content/concepts/discovery-routing/rendezvous.md @@ -23,11 +23,11 @@ serve as a hub for nodes to discover. solutions like DHT and Gossipsub. DHT (Distributed Hash Table) and Gossipsub are decentralized alternatives to Rendezvous. - [DHT]({{< ref "/concepts/discovery-routing/kaddht.md" >}}) is a distributed network protocol used to store and + [DHT]({{< relref "/concepts/discovery-routing/kaddht.md" >}}) is a distributed network protocol used to store and retrieve data in a P2P network efficiently. It is like a hash table mapping keys to values, allowing for fast lookups and efficient data distribution across the network. - [Gossipsub]({{< ref "/concepts/pubsub/overview.md" >}}), on the other hand, is a pub-sub (publish-subscribe) protocol + [Gossipsub]({{< relref "/concepts/pubsub/overview.md" >}}), on the other hand, is a pub-sub (publish-subscribe) protocol that is used to distribute messages and data across a network. It uses a gossip-based mechanism to propagate messages throughout the network, allowing fast and efficient distribution without relying on a central control point. @@ -73,7 +73,7 @@ The rendezvous protocol runs over libp2p streams using the protocol ID `/rendezv ### Rendezvous and publish-subscribe -For effective discovery, rendezvous can be combined with [libp2p publish/subscribe]({{< ref "/concepts/pubsub/overview.md" >}}). +For effective discovery, rendezvous can be combined with [libp2p publish/subscribe]({{< relref "/concepts/pubsub/overview.md" >}}). At a basic level, rendezvous can bootstrap pubsub by discovering peers subscribed to a topic. The rendezvous would be responsible for publishing packets, subscribing, or unsubscribing from packet shapes. diff --git a/content/concepts/fundamentals/addressing.md b/content/concepts/fundamentals/addressing.md index 934f0551..66e2cf66 100644 --- a/content/concepts/fundamentals/addressing.md +++ b/content/concepts/fundamentals/addressing.md @@ -14,19 +14,19 @@ A `multiaddress` (often abbreviated `multiaddr`), is a convention for encoding m For example: `/ip4/192.0.2.0/udp/1234` encodes two protocols along with their essential addressing information. The `/ip4/192.0.2.0` informs us that we want the `192.0.2.0` loopback address of the IPv4 protocol, and `/udp/1234` tells us we want to send UDP packets to port `1234`. -Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash]({{< ref "/concepts/appendix/glossary.md#multihash" >}}) of my IPFS node's public key. +Things get more interesting as we compose further. For example, the multiaddr `/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` uniquely identifies my local IPFS node, using libp2p's [registered protocol id](https://github.com/multiformats/multiaddr/blob/master/protocols.csv) `/p2p/` and the [multihash]({{< relref "/concepts/appendix/glossary.md#multihash" >}}) of my IPFS node's public key. {{< alert icon="💡" context="tip">}} -For more on peer identity and its relation to public key cryptography, see [Peer Identity]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}). +For more on peer identity and its relation to public key cryptography, see [Peer Identity]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}). {{< /alert >}} Let's say that I have the Peer ID `QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N` as above, and my public ip is `198.51.100.0`. I start my libp2p application and listen for connections on TCP port `4242`. -Now I can start [handing out multiaddrs to all my friends]({{< ref "/concepts/appendix/glossary.md#peer-routing" >}}), of the form `/ip4/198.51.100.0/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information. +Now I can start [handing out multiaddrs to all my friends]({{< relref "/concepts/appendix/glossary.md#peer-routing" >}}), of the form `/ip4/198.51.100.0/tcp/4242/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N`. Combining my "location multiaddr" (my IP and port) with my "identity multiaddr" (my libp2p `PeerId`), produces a new multiaddr containing both key pieces of information. Now not only do my friends know where to find me, anyone they give that address to can verify that the machine on the other side is really me, or at least, that they control the private key for my `PeerId`. They also know (by virtue of the `/p2p/` protocol id) that I'm likely to support common libp2p interactions like opening connections and negotiating what application protocols we can use to communicate. That's not bad! -This can be extended to account for multiple layers of addressing and abstraction. For example, the [addresses used for circuit relay]({{< ref "/concepts/nat/circuit-relay.md#relay-addresses" >}}) combine transport addresses with multiple peer identities to form an address that describes a "relay circuit": +This can be extended to account for multiple layers of addressing and abstraction. For example, the [addresses used for circuit relay]({{< relref "/concepts/nat/circuit-relay.md#relay-addresses" >}}) combine transport addresses with multiple peer identities to form an address that describes a "relay circuit": ```shell /ip4/198.51.100.0/tcp/4242/p2p/QmRelay/p2p-circuit/p2p/QmRelayedPeer diff --git a/content/concepts/fundamentals/peers.md b/content/concepts/fundamentals/peers.md index 9e33bfbf..da7108c7 100644 --- a/content/concepts/fundamentals/peers.md +++ b/content/concepts/fundamentals/peers.md @@ -25,7 +25,7 @@ peers. Every private key has a corresponding public key, which is shared with other peers. Together, the public and private key (or "key pair") allow peers to establish -[secure communication]({{< ref "/concepts/secure-comm/overview.md" >}}) channels with each other. +[secure communication]({{< relref "/concepts/secure-comm/overview.md" >}}) channels with each other. Conceptually, a Peer ID is a [cryptographic hash][wiki_hash_function] of a peer's public key. When peers establish a secure channel, the hash can be used to @@ -66,7 +66,7 @@ libp2p multiaddress for me would be: As with other multiaddrs, a `/p2p` address can be encapsulated into another multiaddr to compose into a new multiaddr. For example, I can combine -the above with a [transport]({{< ref "/concepts/transports/overview.md" >}}) address +the above with a [transport]({{< relref "/concepts/transports/overview.md" >}}) address `/ip4/198.51.100.0/tcp/4242` to produce this very useful address: ```shell @@ -78,7 +78,7 @@ transport. If some other peer has taken over that IP address or port, it will be immediately obvious, since they will not have control over the key pair used to produce the Peer ID embedded in the address. -**For more on addresses in libp2p, see [Addressing]({{< ref "/concepts/fundamentals/addressing.md" >}})** +**For more on addresses in libp2p, see [Addressing]({{< relref "/concepts/fundamentals/addressing.md" >}})** {{< alert icon="💡" context="note">}} The multiaddr protocol for libp2p addresses was originally written `/ipfs` and was later renamed to `/p2p`. diff --git a/content/concepts/fundamentals/protocols.md b/content/concepts/fundamentals/protocols.md index ef8e6f40..07ac8b16 100644 --- a/content/concepts/fundamentals/protocols.md +++ b/content/concepts/fundamentals/protocols.md @@ -11,7 +11,7 @@ There are protocols everywhere you look when you're writing network applications especially thick with them. The kind of protocols this article is concerned with are the ones built with libp2p itself, -using the core libp2p abstractions like [transport]({{< ref "/concepts/transports/overview.md" >}}), [peer identity]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}), [addressing]({{< ref "/concepts/fundamentals/addressing.md" >}}), and so on. +using the core libp2p abstractions like [transport]({{< relref "/concepts/transports/overview.md" >}}), [peer identity]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}), [addressing]({{< relref "/concepts/fundamentals/addressing.md" >}}), and so on. Throughout this article, we'll call this kind of protocol that is built with libp2p a **libp2p protocol**, but you may also see them referred to as "wire protocols" or "application protocols". @@ -65,8 +65,8 @@ properties: - Supports backpressure - Readers can't be flooded by eager writers -Behind the scenes, libp2p will also ensure that the stream is [secure]({{< ref "/concepts/secure-comm/overview.md" >}}) and efficiently -[multiplexed]({{< ref "/concepts/multiplex/overview.md" >}}). This is transparent to the protocol handler, which reads and writes +Behind the scenes, libp2p will also ensure that the stream is [secure]({{< relref "/concepts/secure-comm/overview.md" >}}) and efficiently +[multiplexed]({{< relref "/concepts/multiplex/overview.md" >}}). This is transparent to the protocol handler, which reads and writes unencrypted binary data over the stream. The format of the binary data and the mechanics of what to send when and by whom are all up to the protocol to determine. For inspiration, some [common patterns](#common-patterns) that are used in libp2p's internal protocols are outlined below. @@ -160,7 +160,7 @@ The basic identify protocol works by establishing a new stream to a peer using t shown in the table above. When the remote peer opens the new stream, they will fill out an [`Identify` protobuf message][identify_proto] containing -information about themselves, such as their public key, which is used to derive their [`PeerId`]({{< ref "/concepts/fundamentals/peers.md" >}}). +information about themselves, such as their public key, which is used to derive their [`PeerId`]({{< relref "/concepts/fundamentals/peers.md" >}}). Importantly, the `Identify` message includes an `observedAddr` field that contains the [multiaddr][definition_multiaddr] that the peer observed the request coming in on. This helps peers determine their NAT status, since it allows them to @@ -177,7 +177,7 @@ see what other peers observe as their public address and compare it to their own A slight variation on `identify`, the `identify/push` protocol sends the same `Identify` message, but it does so proactively instead of in response to a request. -This is useful if a peer starts listening on a new address, establishes a new [relay circuit]({{< ref "/concepts/nat/circuit-relay.md" >}}), or +This is useful if a peer starts listening on a new address, establishes a new [relay circuit]({{< relref "/concepts/nat/circuit-relay.md" >}}), or learns of its public address from other peers using the standard `identify` protocol. Upon creating or learning of a new address, the peer can push the new address to all peers it's currently aware of. This keeps everyone's routing tables up to date and makes it more likely that other peers will discover the new address. @@ -186,7 +186,7 @@ makes it more likely that other peers will discover the new address. `kad-dht` is a [Distributed Hash Table][wiki_dht] based on the [Kademlia][wiki_kad] routing algorithm, with some modifications. -libp2p uses the DHT as the foundation of its [routing]({{< ref "/concepts/discovery-routing/overview.md" >}}) functionality. To learn more about DHT and the Kademlia algorithm, +libp2p uses the DHT as the foundation of its [routing]({{< relref "/concepts/discovery-routing/overview.md" >}}) functionality. To learn more about DHT and the Kademlia algorithm, check out the [Distributed Hash Tables guide][dht] on the IPFS documentation site. In addition, check out the [libp2p implementations page](https://libp2p.io/implementations/) for updates on all the kad-libp2p implementations. @@ -205,7 +205,7 @@ check out the [Distributed Hash Tables guide][dht] on the IPFS documentation sit [relay_js]: https://github.com/libp2p/js-libp2p-circuit [relay_go]: https://github.com/libp2p/go-libp2p-circuit -As described in the [Circuit Relay article]({{< ref "/concepts/nat/circuit-relay.md" >}}), libp2p provides a protocol +As described in the [Circuit Relay article]({{< relref "/concepts/nat/circuit-relay.md" >}}), libp2p provides a protocol for tunneling traffic through relay peers when two peers are unable to connect to each other directly. See the article for more information on working with relays, including notes on relay addresses and how to enable automatic relay connection when behind an intractable NAT. diff --git a/content/concepts/introduction/overview.md b/content/concepts/introduction/overview.md index 8e37ce28..ef8660ee 100644 --- a/content/concepts/introduction/overview.md +++ b/content/concepts/introduction/overview.md @@ -22,7 +22,7 @@ has something for you. {{< alert icon="" context="">}} If you have any questions or suggestions as you navigate the documentation, -please don't hesitate to [reach out]({{< ref "/concepts/contribute/community.md" >}}), or help +please don't hesitate to [reach out]({{< relref "/concepts/contribute/community.md" >}}), or help improve the documentation by [contributing to the site](https://github.com/libp2p/docs). {{< /alert >}} @@ -36,7 +36,7 @@ libp2p, (short for "library peer-to-peer") is a peer-to-peer (P2P) networking framework that enables the development of P2P applications. It consists of a collection of protocols, specifications, and libraries that facilitate P2P communication between network participants, known as -"[peers]({{< ref "/concepts/fundamentals/peers.md" >}})." +"[peers]({{< relref "/concepts/fundamentals/peers.md" >}})." ### Peer-to-peer basics @@ -85,7 +85,7 @@ There are several reasons to consider using libp2p as a networking layer to crea to fit the specific requirements of any P2P application. - **Extensive transport configurability**: libp2p provides a set of specifications that can be adapted to - support various [transport protocols]({{< ref "/concepts/transports/overview.md" >}}), allowing libp2p applications to operate + support various [transport protocols]({{< relref "/concepts/transports/overview.md" >}}), allowing libp2p applications to operate in various runtime and networking environments as the wealth of transport protocol choices makes it possible to use libp2p in a variety of scenarios. @@ -94,19 +94,19 @@ There are several reasons to consider using libp2p as a networking layer to crea [implemented in many programming languages](https://libp2p.io/implementations/), providing developers with great flexibility when building P2P applications. -- **Security**: libp2p includes [several security features]({{< ref "/concepts/security/security-considerations.md" >}}), +- **Security**: libp2p includes [several security features]({{< relref "/concepts/security/security-considerations.md" >}}), such as peer identity verification using public key cryptography and - [encrypted communication]({{< ref "/concepts/secure-comm/overview.md" >}}) between peers using modern cryptographic algorithms. + [encrypted communication]({{< relref "/concepts/secure-comm/overview.md" >}}) between peers using modern cryptographic algorithms. - **Robustness**: libp2p is a robust and reliable networking protocol that is designed to withstand stress, disturbance, and change. Its features and design choices ensure that it is able to function effectively and efficiently in a wide range of environments, and it is able to recover quickly from disruptions or failures. It also offers protection against network attacks through the use of - [mitigation techniques]({{< ref "/concepts/security/dos-mitigation.md" >}}). + [mitigation techniques]({{< relref "/concepts/security/dos-mitigation.md" >}}). - **Resiliency**: P2P networks are often more resilient than traditional client-server networks, as there is no single point of failure. libp2p includes features such as - [peer discovery and content routing]({{< ref "/concepts/discovery-routing/overview.md" >}}) that help + [peer discovery and content routing]({{< relref "/concepts/discovery-routing/overview.md" >}}) that help to ensure that the network remains available and accessible even if some peers are offline or unreachable. - **Efficiency**: P2P networks can be more efficient in resource utilization, as data is @@ -114,15 +114,15 @@ There are several reasons to consider using libp2p as a networking layer to crea and retrieval patterns that allow developers to distribute data efficiently across the network, making it possible to store and retrieve data in a cost-effective and scalable way. -- **Piercing NAT Barriers**: libp2p is equipped with capabilities for [NAT traversal]({{< ref "/concepts/nat/overview.md" >}}), +- **Piercing NAT Barriers**: libp2p is equipped with capabilities for [NAT traversal]({{< relref "/concepts/nat/overview.md" >}}), which allows P2P communication between peers even when they are behind NAT devices or firewalls. This helps to maintain the connectivity of the network and ensure that it remains accessible despite the presence of these obstacles. - **Message Distribution and Dissemination**: One such pattern libp2p uses is - [publish/subscribe (pubsub)]({{< ref "/concepts/pubsub/overview.md" >}}), which allows a sender (publisher) to send a message + [publish/subscribe (pubsub)]({{< relref "/concepts/pubsub/overview.md" >}}), which allows a sender (publisher) to send a message to multiple recipients (subscribers) without the publisher having to know who the subscribers are. - libp2p implements pubsub through the use of protocols like [gossipsub]({{< ref "/concepts/pubsub/overview.md#gossip" >}}), providing + libp2p implements pubsub through the use of protocols like [gossipsub]({{< relref "/concepts/pubsub/overview.md#gossip" >}}), providing developers with a flexible and efficient means of exchanging data and messages within their P2P applications. diff --git a/content/concepts/multiplex/early-negotiation.md b/content/concepts/multiplex/early-negotiation.md index 01871880..78c1d02a 100644 --- a/content/concepts/multiplex/early-negotiation.md +++ b/content/concepts/multiplex/early-negotiation.md @@ -21,9 +21,9 @@ second [is shown in a diagram here](https://github.com/libp2p/specs/tree/master/connections#upgrading-connections). First, the security protocol is negotiated, then this protocol is used to perform a cryptographic -handshake. libp2p currently supports [Noise]({{< ref "/concepts/secure-comm/noise.md" >}}) and [TLS 1.3]({{< ref "/concepts/secure-comm/tls.md" >}}). +handshake. libp2p currently supports [Noise]({{< relref "/concepts/secure-comm/noise.md" >}}) and [TLS 1.3]({{< relref "/concepts/secure-comm/tls.md" >}}). Once the cryptographic handshake completes, multistream-select runs again on top of -the secured connection to negotiate a steam multiplexer, like [yamux]({{< ref "/concepts/multiplex/yamux.md" >}}) or [mplex]({{< ref "/concepts/multiplex/mplex.md" >}}). +the secured connection to negotiate a steam multiplexer, like [yamux]({{< relref "/concepts/multiplex/yamux.md" >}}) or [mplex]({{< relref "/concepts/multiplex/mplex.md" >}}). diff --git a/content/concepts/multiplex/mplex.md b/content/concepts/multiplex/mplex.md index 8affc505..26175b1c 100644 --- a/content/concepts/multiplex/mplex.md +++ b/content/concepts/multiplex/mplex.md @@ -13,7 +13,7 @@ is now considered critical for a stream multiplexer. mplex runs over a reliable, ordered pipe between two peers, such as a TCP connection. Peers can open, write to, close, and reset a stream. mplex uses a message-based framing -layer like [yamux]({{< ref "/concepts/multiplex/yamux.md" >}}), enabling it to multiplex different +layer like [yamux]({{< relref "/concepts/multiplex/yamux.md" >}}), enabling it to multiplex different data streams, including stream-oriented data and other types of messages. ### Drawbacks diff --git a/content/concepts/multiplex/overview.md b/content/concepts/multiplex/overview.md index 9e224c1c..e12d3617 100644 --- a/content/concepts/multiplex/overview.md +++ b/content/concepts/multiplex/overview.md @@ -51,10 +51,10 @@ and allowing for the seamless transmission of multiple streams of data over a si connection. {{< /alert >}} -Currently, libp2p supports two stream muxers, [mplex]({{< ref "/concepts/multiplex/mplex.md" >}}) -and [yamux]({{< ref "/concepts/multiplex/yamux.md" >}}). However, many of the -[transport protocols]({{< ref "/concepts/transports/overview.md" >}}) available in the libp2p stack -come with native streams, such as [QUIC]({{< ref "/concepts/transports/quic.md" >}}), -[WebTransport]({{< ref "/concepts/transports/webtransport.md" >}}), and -[WebRTC]({{< ref "/concepts/transports/webrtc.md" >}}), and in these cases, libp2p +Currently, libp2p supports two stream muxers, [mplex]({{< relref "/concepts/multiplex/mplex.md" >}}) +and [yamux]({{< relref "/concepts/multiplex/yamux.md" >}}). However, many of the +[transport protocols]({{< relref "/concepts/transports/overview.md" >}}) available in the libp2p stack +come with native streams, such as [QUIC]({{< relref "/concepts/transports/quic.md" >}}), +[WebTransport]({{< relref "/concepts/transports/webtransport.md" >}}), and +[WebRTC]({{< relref "/concepts/transports/webrtc.md" >}}), and in these cases, libp2p **does not need to perform stream multiplexing** as the protocol already provides it. diff --git a/content/concepts/multiplex/switch.md b/content/concepts/multiplex/switch.md index abce4e03..c0b8c595 100644 --- a/content/concepts/multiplex/switch.md +++ b/content/concepts/multiplex/switch.md @@ -9,4 +9,4 @@ libp2p maintains some state about known peers and existing connections in a comp When configuring libp2p, applications enable stream muxing modules, which the switch will use when dialing peers and listening for connections. If the remote peers support any of the same stream muxing implementations, the switch will select and use it when establishing the connection. If you dial a peer that the switch already has an open connection to, the new stream will automatically be multiplexed over the existing connection. -Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams. +Reaching agreement on which stream multiplexer to use happens early in the connection establishment process. Peers use [protocol negotiation]({{< relref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}) to agree on a commonly supported multiplexer, which upgrades a "raw" transport connection into a muxed connection capable of opening new streams. diff --git a/content/concepts/nat/autonat.md b/content/concepts/nat/autonat.md index 8107a61f..65e47614 100644 --- a/content/concepts/nat/autonat.md +++ b/content/concepts/nat/autonat.md @@ -65,7 +65,7 @@ whether or not it is behind a NAT. > If the response indicates success, the node is likely not behind a NAT and does > not need to use a relay server to improve its connectivity. If the response indicates > an error, the node is likely behind a NAT and may need to use a -> [relay server]({{< ref "/concepts/nat/dcutr.md" >}}) to communicate with other nodes in the network. +> [relay server]({{< relref "/concepts/nat/dcutr.md" >}}) to communicate with other nodes in the network. {{< alert icon="" context="caution">}} To prevent diff --git a/content/concepts/nat/circuit-relay.md b/content/concepts/nat/circuit-relay.md index f6a49166..1518bc9e 100644 --- a/content/concepts/nat/circuit-relay.md +++ b/content/concepts/nat/circuit-relay.md @@ -9,9 +9,9 @@ aliases: ## What is Circuit Relay? -Circuit relay is a [transport protocol]({{< ref "/concepts/transports/overview.md" >}}) that routes traffic between two peers over a third-party "relay" peer. +Circuit relay is a [transport protocol]({{< relref "/concepts/transports/overview.md" >}}) that routes traffic between two peers over a third-party "relay" peer. -In many cases, peers will be unable to [traverse their NAT and/or firewall]({{< ref "/concepts/nat/overview.md" >}}) in a way that makes them publicly accessible. Or they may not share common [transport protocols]({{< ref "/concepts/transports/overview.md" >}}) that would allow them to communicate directly. +In many cases, peers will be unable to [traverse their NAT and/or firewall]({{< relref "/concepts/nat/overview.md" >}}) in a way that makes them publicly accessible. Or they may not share common [transport protocols]({{< relref "/concepts/transports/overview.md" >}}) 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]. When a peer isn't able to listen on a public address, it can dial out to a relay peer, which will keep a long-lived connection open. Other peers will be able to dial through the relay peer using a `p2p-circuit` address, which will forward traffic to its destination. @@ -30,7 +30,7 @@ Today there are two versions of the circuit relay protocol, [v1](https://github. ## Relay addresses -A relay circuit is identified using a [multiaddr][definition_multiaddress] that includes the [Peer ID]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer whose traffic is being relayed (the listening peer or "relay target"). +A relay circuit is identified using a [multiaddr][definition_multiaddress] that includes the [Peer ID]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer whose traffic is being relayed (the listening peer or "relay target"). Let's say that I have a peer with the Peer ID `QmAlice`. I want to give out my address to my friend `QmBob`, but I'm behind a NAT that won't let anyone dial me directly. @@ -38,7 +38,7 @@ The most basic `p2p-circuit` address I can construct looks like this: `/p2p-circuit/p2p/QmAlice` -The address above is interesting, because it doesn't include any [transport]({{< ref "/concepts/transports/overview.md" >}}) addresses for either the peer we want to contact (`QmAlice`) or for the relay peer that will convey the traffic. Without that information, the only chance a peer has of dialing me is to discover a relay and hope they have a connection to me. +The address above is interesting, because it doesn't include any [transport]({{< relref "/concepts/transports/overview.md" >}}) addresses for either the peer we want to contact (`QmAlice`) or for the relay peer that will convey the traffic. Without that information, the only chance a peer has of dialing me is to discover a relay and hope they have a connection to me. A better address would be something like `/p2p/QmRelay/p2p-circuit/p2p/QmAlice`. This includes the identity of a specific relay peer, `QmRelay`. If a peer already knows how to open a connection to `QmRelay`, they'll be able to reach us. @@ -60,10 +60,10 @@ The below sequence diagram depicts a sample relay process: ![Circuit v2 Protocol Interaction](https://raw.githubusercontent.com/libp2p/specs/master/relay/circuit-v2.svg) -1. Node `A` is behind a NAT and/or firewall, e.g. detected via the [AutoNAT service]({{< ref "/concepts/nat/autonat.md" >}}). +1. Node `A` is behind a NAT and/or firewall, e.g. detected via the [AutoNAT service]({{< relref "/concepts/nat/autonat.md" >}}). 2. Node `A` therefore requests a reservation with relay `R`. I.e. node `A` asks relay `R` to listen for incoming connections on its behalf. 3. Node `B` wants to establish a connection to node `A`. Given that node `A` does not advertise any direct addresses but only a relay address, node `B` connects to relay `R`, asking relay `R` to relay a connection to `A`. 4. Relay `R` forwards the connection request to node `A` and eventually relays all data send by `A` and `B`. [spec_relay]: https://github.com/libp2p/specs/tree/master/relay -[definition_multiaddress]: /concepts/appendix/glossary#multiaddr +[definition_multiaddress]: {{< relref "/concepts/appendix/glossary#multiaddr" >}} diff --git a/content/concepts/nat/dcutr.md b/content/concepts/nat/dcutr.md index df7d1ba0..400f26cc 100644 --- a/content/concepts/nat/dcutr.md +++ b/content/concepts/nat/dcutr.md @@ -8,7 +8,7 @@ weight: 210 Relays are used to traverse NATs by acting as proxies, but this can be expensive to scale and maintain, and may result in low-bandwidth, high-latency -connections. [Hole punching]({{< ref "/concepts/nat/hole-punching.md" >}}) is another technique +connections. [Hole punching]({{< relref "/concepts/nat/hole-punching.md" >}}) is another technique that enables NAT traversal by enabling two nodes behind NATs to communicate directly. However, in addition to relay nodes, it requires another piece of infrastructure called signaling servers. @@ -35,7 +35,7 @@ The DCUtR protocol uses the protocol ID `/libp2p/dcutr` and involves the exchange of `Connect` and `Sync` messages. The DCUtR protocol supports different types of connections, such as TCP and -[QUIC]({{< ref "/concepts/transports/quic.md" >}}), the process of establishing a connection is +[QUIC]({{< relref "/concepts/transports/quic.md" >}}), the process of establishing a connection is different for each type. @Dennis-tra has a [great talk](https://www.youtube.com/watch?v=fyhZWlDbcyM) on diff --git a/content/concepts/nat/hole-punching.md b/content/concepts/nat/hole-punching.md index 8ac4dc1a..d9fd4f7e 100644 --- a/content/concepts/nat/hole-punching.md +++ b/content/concepts/nat/hole-punching.md @@ -97,7 +97,7 @@ a hole punching phase. ### Phase I: Preparation -1. [AutoNAT]({{< ref "/concepts/nat/autonat.md" >}}): Determine whether a node is dialable, +1. [AutoNAT]({{< relref "/concepts/nat/autonat.md" >}}): Determine whether a node is dialable, as in, discover if a node is behind a NAT or firewall. > This is equivalent to the @@ -131,7 +131,7 @@ a hole punching phase. for the closest peers to its Peer ID or choose a subset of the public nodes it is already connected to. -2. [Circuit Relay]({{< ref "/concepts/nat/circuit-relay.md" >}}): Connect to and request +2. [Circuit Relay]({{< relref "/concepts/nat/circuit-relay.md" >}}): Connect to and request reservations with the discovered relay nodes. A node can advertise itself as being reachable through a remote relay node. @@ -152,7 +152,7 @@ a hole punching phase. ### Phase II: Hole punching -1. [Circuit Relay]({{< ref "/concepts/nat/circuit-relay.md" >}}): Establish a secure relay connection +1. [Circuit Relay]({{< relref "/concepts/nat/circuit-relay.md" >}}): Establish a secure relay connection through the public relay node. Node `A` establishes a direct connection with the relay node. Node `B` then requests a relayed connection to node `A` through the relay node, creating a bi-directional channel and uses TLS to secure the diff --git a/content/concepts/nat/overview.md b/content/concepts/nat/overview.md index f1142210..77b43e07 100644 --- a/content/concepts/nat/overview.md +++ b/content/concepts/nat/overview.md @@ -8,7 +8,7 @@ aliases: ## Overview -The internet is composed of countless networks, bound together into shared address spaces by foundational [transport protocols]({{< ref "/concepts/transports/overview.md" >}}). +The internet is composed of countless networks, bound together into shared address spaces by foundational [transport protocols]({{< relref "/concepts/transports/overview.md" >}}). As traffic moves between network boundaries, it's very common for a process called Network Address Translation to occur. Network Address Translation (NAT) maps an address from one address space to another. diff --git a/content/concepts/secure-comm/overview.md b/content/concepts/secure-comm/overview.md index b80ba4c1..219da170 100644 --- a/content/concepts/secure-comm/overview.md +++ b/content/concepts/secure-comm/overview.md @@ -12,12 +12,12 @@ Before two peers can transmit data, the communication channel they establish needs to be secured. By design, libp2p supports many different transports (TCP, QUIC, WebSocket, WebTransport, etc.). Some transports have built-in encryption at the transport layer -like [QUIC]({{< ref "/concepts/transports/quic.md" >}}), while other transports (e.g. TCP, WebSocket) +like [QUIC]({{< relref "/concepts/transports/quic.md" >}}), while other transports (e.g. TCP, WebSocket) lack native security and require a security handshake after the transport connection has been established. ## Secure channels in libp2p -libp2p specifies two security protocols, [TLS 1.3]({{< ref "/concepts/secure-comm/tls.md" >}}) and [Noise]({{< ref "/concepts/secure-comm/noise.md" >}}). +libp2p specifies two security protocols, [TLS 1.3]({{< relref "/concepts/secure-comm/tls.md" >}}) and [Noise]({{< relref "/concepts/secure-comm/noise.md" >}}). After the handshake has finished, we need to negotiate a -[stream multiplexer]({{< ref "/concepts/multiplex/overview.md" >}}) for the connection. +[stream multiplexer]({{< relref "/concepts/multiplex/overview.md" >}}) for the connection. diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 97afd143..032e8441 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -7,7 +7,7 @@ aliases: --- TLS (Transport Layer Security) is one of the security handshakes used to secure transports -that don't have built-in security (e.g. TCP, WebSocket). [Noise]({{< ref "/concepts/secure-comm/noise.md" >}}), an alternative to +that don't have built-in security (e.g. TCP, WebSocket). [Noise]({{< relref "/concepts/secure-comm/noise.md" >}}), an alternative to TLS, is also another security handshake used to secure transports. ## What is TLS? diff --git a/content/concepts/security/security-considerations.md b/content/concepts/security/security-considerations.md index 223374c4..54907cf2 100644 --- a/content/concepts/security/security-considerations.md +++ b/content/concepts/security/security-considerations.md @@ -29,7 +29,7 @@ reasonably succeed. ## Identity and Trust -Every libp2p peer is uniquely identified by their [Peer ID]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}), which +Every libp2p peer is uniquely identified by their [Peer ID]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}), which is derived from a private cryptographic key. Peer ids and their corresponding keys allow us to _authenticate_ remote peers, so that we can be sure we're talking to the correct peer and not an imposter. @@ -48,7 +48,7 @@ To design an authorization system on libp2p, you can rely on the authentication of peer ids and build an association between peer ids and permissions, with the Peer ID serving the same function as the "username" in traditional authorization frameworks, and the peer's private key serving as the "password". -Your [protocol handler]({{< ref "/concepts/fundamentals/protocols.md#handler-functions" >}}) could then +Your [protocol handler]({{< relref "/concepts/fundamentals/protocols.md#handler-functions" >}}) could then reject requests from untrusted peers. Of course, it's also possible to build other kinds of authorization systems on @@ -141,7 +141,7 @@ returning dishonest routing information. ### Publish / Subscribe -libp2p's [publish/subscribe protocol]({{< ref "/concepts/pubsub/overview.md" >}}) allows a peer +libp2p's [publish/subscribe protocol]({{< relref "/concepts/pubsub/overview.md" >}}) allows a peer to broadcast messages to other peers within a given "topic." By default, the `gossipsub` implementation will sign all messages with the @@ -159,6 +159,6 @@ attacks. We expect this to lead to a more robust and attack-resistant pubsub protocol, but it is unlikely to prevent all classes of possible attack by determined bad actors. -[glossary-dht]: /concepts/appendix/glossary#dht +[glossary-dht]: {{< relref "/concepts/appendix/glossary#dht" >}} [wikipedia-sybil]: https://en.wikipedia.org/wiki/Sybil_attack [paper-s-kademlia]: https://telematics.tm.kit.edu/publications/Files/267/SKademlia_2007.pdf diff --git a/content/concepts/transports/listen-and-dial.md b/content/concepts/transports/listen-and-dial.md index 3998d3cd..9d037bd5 100644 --- a/content/concepts/transports/listen-and-dial.md +++ b/content/concepts/transports/listen-and-dial.md @@ -28,7 +28,7 @@ reach them. Because each transport will likely require its own address scheme, libp2p uses a convention called a "multiaddress" or `multiaddr` to encode many different addressing schemes. -The [addressing doc]({{< ref "/concepts/fundamentals/addressing.md" >}}) goes into more detail, but an overview +The [addressing doc]({{< relref "/concepts/fundamentals/addressing.md" >}}) goes into more detail, but an overview of how multiaddresses work is helpful for understanding the dial and listen interfaces. @@ -43,15 +43,15 @@ has the advantage of being explicit about the protocols that are being described. With the multiaddr, you can see at a glance that the `198.51.100.0` address belongs to the IPv4 protocol, and the `6543` belongs to TCP. -For more complex examples, see [addressing]({{< ref "/concepts/fundamentals/addressing.md" >}}). +For more complex examples, see [addressing]({{< relref "/concepts/fundamentals/addressing.md" >}}). Both dial and listen deal with multiaddresses. When listening, you give the transport the address you'd like to listen on, and when dialing you provide the address to dial to. When dialing a remote peer, the multiaddress should include the -[PeerId]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer you're trying to reach. -This lets libp2p establish a [secure communication channel]({{< ref "/concepts/secure-comm/overview.md" >}}) +[PeerId]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer you're trying to reach. +This lets libp2p establish a [secure communication channel]({{< relref "/concepts/secure-comm/overview.md" >}}) and prevents impersonation. An example multiaddress that includes a `PeerId`: @@ -62,7 +62,7 @@ An example multiaddress that includes a `PeerId`: The `/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6` component uniquely identifies the remote peer using the hash of its public key. -For more, see the [peer identity content]({{< ref "/concepts/fundamentals/peers.md#peer-id" >}}). +For more, see the [peer identity content]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}). {{< alert icon="💡" context="tip">}} When peer routing is enabled, you can dial peers using just their PeerId, @@ -78,9 +78,9 @@ in a web browser. The libp2p component responsible for managing the transports is called the [switch][definition_switch], which also coordinates -[protocol negotiation]({{< ref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}), -[stream multiplexing]({{< ref "/concepts/multiplex/overview.md" >}}), -[establishing secure communication]({{< ref "/concepts/secure-comm/overview.md" >}}) and other forms of +[protocol negotiation]({{< relref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}), +[stream multiplexing]({{< relref "/concepts/multiplex/overview.md" >}}), +[establishing secure communication]({{< relref "/concepts/secure-comm/overview.md" >}}) and other forms of "connection upgrading". The switch provides a single "entry point" for dialing and listening, and frees @@ -89,4 +89,4 @@ and other pieces of the "connection stack" that are used under the hood. {{< alert icon="💡" context="note" text="The term \"swarm\" was previously used to refer to what is now called the \"switch\", and some places in the codebase still use the \"swarm\" terminology." />}} -[definition_switch]: /concepts/appendix/glossary#switch +[definition_switch]: {{< relref "/concepts/appendix/glossary#switch" >}} diff --git a/content/concepts/transports/webrtc.md b/content/concepts/transports/webrtc.md index 286ed317..7ffd213c 100644 --- a/content/concepts/transports/webrtc.md +++ b/content/concepts/transports/webrtc.md @@ -42,7 +42,7 @@ The features employed in libp2p are: to a peer. This means libp2p can utilize data channels as a transport to send raw data to peers and enables applications to build anything they like. -- [NAT traversal]({{< ref "/concepts/nat/overview.md" >}}): WebRTC includes mechanisms (like +- [NAT traversal]({{< relref "/concepts/nat/overview.md" >}}): WebRTC includes mechanisms (like [ICE](https://datatracker.ietf.org/doc/rfc5245/)) to connect to nodes that run behind NATs and firewalls. In non-decentralized WebRTC, this can be facilitated by a [TURN server.](https://webrtc.org/getting-started/turn-server), @@ -97,7 +97,7 @@ When establishing a WebRTC connection, the browser and server perform a standard handshake as part of the connection setup. Of the three primary focuses of information security, a successful DTLS handshake only provides two: confidentiality and integrity. Authenticity is achieved by succeeding the -[Noise handshake]({{< ref "/concepts/secure-comm/noise.md" >}}) following the DTLS handshake. +[Noise handshake]({{< relref "/concepts/secure-comm/noise.md" >}}) following the DTLS handshake. From 7659645f75ffc4c53a6e159775fc325e0019bfad Mon Sep 17 00:00:00 2001 From: Daniel Chiquito Date: Fri, 11 Aug 2023 14:31:40 -0400 Subject: [PATCH 16/17] Remove link-check.yml workflow --- .github/workflows/link-check.yml | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 .github/workflows/link-check.yml diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml deleted file mode 100644 index 37c55487..00000000 --- a/.github/workflows/link-check.yml +++ /dev/null @@ -1,23 +0,0 @@ -name: links - -on: - push: - branches: master - pull_request: - branches: master - -jobs: - linkChecker: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Link Checker - uses: lycheeverse/lychee-action@v1.8.0 - with: - # Check all markdown in /content/ - # Ignore twitter.com links because they all 503 unless logged in - args: --no-progress --exclude twitter.com ./content - fail: true - env: - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} From a70a1d03a729c46a6acd840d8b394a3433015c67 Mon Sep 17 00:00:00 2001 From: Prithvi Shahi Date: Fri, 11 Aug 2023 18:37:24 -0700 Subject: [PATCH 17/17] Update content/concepts/fundamentals/peers.md --- content/concepts/fundamentals/peers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/fundamentals/peers.md b/content/concepts/fundamentals/peers.md index da7108c7..203a2484 100644 --- a/content/concepts/fundamentals/peers.md +++ b/content/concepts/fundamentals/peers.md @@ -78,7 +78,7 @@ transport. If some other peer has taken over that IP address or port, it will be immediately obvious, since they will not have control over the key pair used to produce the Peer ID embedded in the address. -**For more on addresses in libp2p, see [Addressing]({{< relref "/concepts/fundamentals/addressing.md" >}})** +For more on addresses in libp2p, see [Addressing]({{< relref "/concepts/fundamentals/addressing.md" >}}) {{< alert icon="💡" context="note">}} The multiaddr protocol for libp2p addresses was originally written `/ipfs` and was later renamed to `/p2p`.