fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-06-26 08:11:39 +00:00
Code Issues Projects Releases Wiki Activity

src/tutorials: Add hole punching tutorial (#2460)

Browse Source
This commit is contained in:
Max Inden
2022-02-10 16:36:20 +01:00
committed by GitHub
parent b39770b8e9
commit 861e15dabb
5 changed files with 155 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
src/tutorials/hole_punching.rs Normal file
View File

@ -0,0 +1,150 @@
// Copyright 2022 Protocol Labs.
//
// Permission is hereby granted, free of charge, to any person obtaining a
// copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//! # Hole Punching Tutorial
//!
//! This tutorial shows hands-on how to overcome firewalls and NATs with libp2p's hole punching
//! mechanism. Before we get started, please read the [blog
//! post](https://github.com/ipfs/ipfs-blog/pull/375) to familiarize yourself with libp2p's hole
//! punching mechanism on a conceptual level.
//!
//! We will be using the [Circuit Relay v2](crate::relay::v2) and the [Direct Connection
//! Upgrade through Relay (DCUtR)](crate::dcutr) protocol.
//!
//! You will need 3 machines for this tutorial:
//!
//! - A relay server
//! - Any public server will do, e.g. a cloud provider VM.
//! - A listening client.
//! - Any computer connected to the internet, but not reachable from outside its own network,
//! works.
//! - This can e.g. be your friends laptop behind their router (firewall + NAT).
//! - This can e.g. be some cloud provider VM, shielded from incoming connections e.g. via
//! Linux's UFW on the same machine.
//! - Don't use a machine that is in the same network as the dialing client. (This would require
//! NAT hairpinning.)
//! - A dialing client.
//! - Like the above, any computer connected to the internet, but not reachable from the outside.
//! - Your local machine will likely fulfill these requirements.
//!
//! ## Setting up the relay server
//!
//! Hole punching requires a public relay node for the two private nodes to coordinate their hole
//! punch via. For that we need a public server somewhere in the Internet. In case you don't have
//! one already, any cloud provider VM will do.
//!
//! Either on the server directly, or on your local machine, compile the example relay server:
//!
//! ``` bash
//! ## Inside the rust-libp2p repository.
//! cargo build --example relay_v2 -p libp2p-relay
//! ```
//!
//! You can find the binary at `target/debug/examples/relay_v2`. In case you built it locally, copy
//! it to your server.
//!
//! On your server, start the relay server binary:
//!
//! ``` bash
//! ./relay_v2 --port 4001 --secret-key-seed 0
//! ```
//!
//! Now let's make sure that the server is public, in other words let's make sure one can reach it
//! through the Internet. From the dialing client:
//!
//! 1. Test that you can connect on Layer 3 (IP).
//!
//! ``` bash
//! ping $RELAY_SERVER_IP
//! ```
//!
//! 2. Test that you can connect on Layer 4 (TCP).
//!
//! ``` bash
//! telnet $RELAY_SERVER_IP 4001
//! ```
//!
//! 3. Test that you can connect via libp2p using [`libp2p-lookup`](https://github.com/mxinden/libp2p-lookup).
//!
//! ``` bash
//! ## For IPv4
//! libp2p-lookup direct --address /ip4/$RELAY_SERVER_IP
//! ## For IPv6
//! libp2p-lookup direct --address /ip6/$RELAY_SERVER_IP
//! ```
//!
//! ## Setting up the listening client
//!
//! Either on the listening client machine directly, or on your local machine, compile the example
//! DCUtR client:
//!
//! ``` bash
//! ## Inside the rust-libp2p repository.
//! cargo build --example client -p libp2p-dcutr
//! ```
//!
//! You can find the binary at `target/debug/examples/client`. In case you built it locally, copy
//! it to your listening client machine.
//!
//! On the listening client machine
//!
//! ``` bash
//! RUST_LOG=info ./client --secret-key-seed 1 --mode listen --relay-address /dns4/$RELAY_SERVER_IP/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN
//! ```
//!
//! Now let's make sure that the listening client is not public, in other words let's make sure one
//! can not reach it directly through the Internet. From the dialing client test that you can not
//! connect on Layer 4 (TCP):
//!
//! ``` bash
//! telnet $RELAY_SERVER_IP 4001
//! ```
//!
//! ## Connecting to the listening client from the dialing client
//!
//! ``` bash
//! RUST_LOG=info ./client --secret-key-seed 2 --mode dial --relay-address /dns4/$RELAY_SERVER_IP/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN --remote-peer-id 12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X
//! ```
//!
//! You should see the following logs appear:
//!
//! 1. The dialing client establishing a relayed connection to the listening client via the relay
//! server. Note the [`/p2p-circuit` protocol](crate::multiaddr::Protocol::P2pCircuit) in the
//! [`Multiaddr`](crate::Multiaddr).
//!
//! ``` ignore
//! [2022-01-30T12:54:10Z INFO client] Established connection to PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") via Dialer { address: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X", role_override: Dialer }
//! ```
//!
//! 2. The listening client initiating a direct connection upgrade for the new relayed connection.
//! Reported by [`dcutr`](crate::dcutr) through
//! [`Event::RemoteInitiatedDirectConnectionUpgrade`](crate::dcutr::behaviour::Event::RemoteInitiatedDirectConnectionUpgrade).
//!
//! ``` ignore
//! [2022-01-30T12:54:11Z INFO client] RemoteInitiatedDirectConnectionUpgrade { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X"), remote_relayed_addr: "/ip4/$RELAY_PEER_ID/tcp/4001/p2p/12D3KooWDpJ7As7BWAwRMfu1VU2WCqNjvq387JEYKDBj4kx6nXTN/p2p-circuit/p2p/12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X" }
//! ```
//!
//! 3. The direct connection upgrade, also known as hole punch, succeeding. Reported by
//! [`dcutr`](crate::dcutr) through
//! [`Event::RemoteInitiatedDirectConnectionUpgrade`](crate::dcutr::behaviour::Event::DirectConnectionUpgradeSucceeded).
//!
//! ``` ignore
//! [2022-01-30T12:54:11Z INFO client] DirectConnectionUpgradeSucceeded { remote_peer_id: PeerId("12D3KooWPjceQrSwdWXPyLLeABRXmuqt69Rg3sBYbU1Nft9HyQ6X") }
//! ```

363
src/tutorials/ping.rs Normal file
View File

@ -0,0 +1,363 @@
// Copyright 2021 Protocol Labs.
//
// Permission is hereby granted, free of charge, to any person obtaining a
// copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
//! # Ping Tutorial - Getting started with rust-libp2p
//!
//! This tutorial aims to give newcomers a hands-on overview on how to use the
//! Rust libp2p implementation. People new to Rust likely want to get started on
//! [Rust](https://www.rust-lang.org/) itself, before diving into all the
//! networking fun. This library makes heavy use of asynchronous Rust. In case
//! you are not familiar with these concepts the Rust
//! [async-book](https://rust-lang.github.io/async-book/) should prove useful.
//! People new to libp2p might prefer to get a general overview at libp2p.io
//! first, though libp2p knowledge is not required for this tutorial.
//!
//! We are going to build a small `ping` clone, sending a ping to a peer,
//! expecting a pong as a response.
//!
//! ## Scaffolding
//!
//! Let's start off by
//!
//! 1. Creating a new crate: `cargo init rust-libp2p-tutorial`
//!
//! 2. Adding `libp2p` as well as `futures` as a dependency in the
//! `Cargo.toml` file. We will also include `async-std` with the
//! "attributes" feature to allow for an `async main`:
//!
//! ```yaml
//! [package]
//! name = "rust-libp2p-tutorial"
//! version = "0.1.0"
//! authors = ["Max Inden <mail@max-inden.de>"]
//! edition = "2021"
//! rust-version = "1.56.1"
//!
//! [dependencies]
//! libp2p = "<insert-current-version-here>"
//! futures = "<insert-current-version-here>"
//! async-std = { version = "<insert-current-version-here>", features = ["attributes"] }
//! ```
//!
//! ## Network identity
//!
//! With all the scaffolding in place, we can dive into the libp2p specifics. At
//! first we need to create a network identity for our local node in `async fn
//! main()`, annotated with an attribute to allow `main` to be `async`.
//! Identities in libp2p are handled via a public and private key pair.
//! Nodes identify each other via their [`PeerId`](crate::PeerId) which is
//! derived from the public key.
//!
//! ```rust
//! use libp2p::{identity, PeerId};
//! use std::error::Error;
//!
//! #[async_std::main]
//! async fn main() -> Result<(), Box<dyn Error>> {
//! let local_key = identity::Keypair::generate_ed25519();
//! let local_peer_id = PeerId::from(local_key.public());
//! println!("Local peer id: {:?}", local_peer_id);
//!
//! Ok(())
//! }
//! ```
//!
//! You can already run the code above via `cargo run` which should print a
//! different [`PeerId`](crate::PeerId) each time, given that we randomly
//! generate the key pair.
//!
//! ## Transport
//!
//! Next up we need to construct a transport. After all, we want to send some
//! bytes from A to B. A transport in libp2p provides connection-oriented
//! communication channels (e.g. TCP) as well as upgrades on top of those like
//! authentication and encryption protocols. Technically, a libp2p transport is
//! anything that implements the [`Transport`] trait.
//!
//! Instead of constructing a transport ourselves for this tutorial, we use the
//! convenience function [`development_transport`](crate::development_transport)
//! that creates a TCP transport with [`noise`](crate::noise) for authenticated
//! encryption.
//!
//! Furthermore, [`development_transport`] builds a multiplexed transport,
//! whereby multiple logical substreams can coexist on the same underlying (TCP)
//! connection. For further details on substream multiplexing, take a look at
//! [`crate::core::muxing`] and [`yamux`](crate::yamux).
//!
//! ```rust
//! use libp2p::{identity, PeerId};
//! use std::error::Error;
//!
//! #[async_std::main]
//! async fn main() -> Result<(), Box<dyn Error>> {
//! let local_key = identity::Keypair::generate_ed25519();
//! let local_peer_id = PeerId::from(local_key.public());
//! println!("Local peer id: {:?}", local_peer_id);
//!
//! let transport = libp2p::development_transport(local_key).await?;
//!
//! Ok(())
//! }
//! ```
//!
//! ## Network behaviour
//!
//! Now it is time to look at another core trait of rust-libp2p - the
//! [`NetworkBehaviour`]. While the previously introduced trait [`Transport`]
//! defines _how_ to send bytes on the network, a [`NetworkBehaviour`] defines
//! _what_ bytes to send on the network.
//!
//! To make this more concrete, let's take a look at a simple implementation of
//! the [`NetworkBehaviour`] trait - the [`Ping`](crate::ping::Ping)
//! [`NetworkBehaviour`]. As you might have guessed, similar to the good old
//! `ping` network tool, libp2p [`Ping`](crate::ping::Ping) sends a ping to a
//! remote and expects to receive a pong in turn. The
//! [`Ping`](crate::ping::Ping) [`NetworkBehaviour`] does not care _how_ the
//! ping or pong messages are send on the network, whether they are sent via
//! TCP, whether they are encrypted via [noise](crate::noise) or just in
//! [plaintext](crate::plaintext). It only cares about _what_ messages are sent
//! on the network.
//!
//! The two traits [`Transport`] and [`NetworkBehaviour`] allow us to cleanly
//! separate _how_ to send bytes from _what_ bytes to send.
//!
//! With the above in mind, let's extend our example, creating a
//! [`Ping`](crate::ping::Ping) [`NetworkBehaviour`] at the end:
//!
//! ```rust
//! use libp2p::{identity, PeerId};
//! use libp2p::ping::{Ping, PingConfig};
//! use std::error::Error;
//!
//! #[async_std::main]
//! async fn main() -> Result<(), Box<dyn Error>> {
//! let local_key = identity::Keypair::generate_ed25519();
//! let local_peer_id = PeerId::from(local_key.public());
//! println!("Local peer id: {:?}", local_peer_id);
//!
//! let transport = libp2p::development_transport(local_key).await?;
//!
//! // Create a ping network behaviour.
//! //
//! // For illustrative purposes, the ping protocol is configured to
//! // keep the connection alive, so a continuous sequence of pings
//! // can be observed.
//! let behaviour = Ping::new(PingConfig::new().with_keep_alive(true));
//!
//! Ok(())
//! }
//! ```
//!
//! ## Swarm
//!
//! Now that we have a [`Transport`] and a [`NetworkBehaviour`], we need
//! something that connects the two, allowing both to make progress. This job is
//! carried out by a [`Swarm`]. Put simply, a [`Swarm`] drives both a
//! [`Transport`] and a [`NetworkBehaviour`] forward, passing commands from the
//! [`NetworkBehaviour`] to the [`Transport`] as well as events from the
//! [`Transport`] to the [`NetworkBehaviour`].
//!
//! ```rust
//! use libp2p::{identity, PeerId};
//! use libp2p::ping::{Ping, PingConfig};
//! use libp2p::swarm::Swarm;
//! use std::error::Error;
//!
//! #[async_std::main]
//! async fn main() -> Result<(), Box<dyn Error>> {
//! let local_key = identity::Keypair::generate_ed25519();
//! let local_peer_id = PeerId::from(local_key.public());
//! println!("Local peer id: {:?}", local_peer_id);
//!
//! let transport = libp2p::development_transport(local_key).await?;
//!
//! // Create a ping network behaviour.
//! //
//! // For illustrative purposes, the ping protocol is configured to
//! // keep the connection alive, so a continuous sequence of pings
//! // can be observed.
//! let behaviour = Ping::new(PingConfig::new().with_keep_alive(true));
//!
//! let mut swarm = Swarm::new(transport, behaviour, local_peer_id);
//!
//! Ok(())
//! }
//! ```
//!
//! ## Multiaddr
//!
//! With the [`Swarm`] in place, we are all set to listen for incoming
//! connections. We only need to pass an address to the [`Swarm`], just like for
//! [`std::net::TcpListener::bind`]. But instead of passing an IP address, we
//! pass a [`Multiaddr`] which is yet another core concept of libp2p worth
//! taking a look at.
//!
//! A [`Multiaddr`] is a self-describing network address and protocol stack that
//! is used to establish connections to peers. A good introduction to
//! [`Multiaddr`] can be found on https://docs.libp2p.io/concepts/addressing/
//! and its specification repository https://github.com/multiformats/multiaddr.
//!
//! Let's make our local node listen on a new socket.
//! This socket is listening on multiple network interfaces at the same time. For
//! each network interface, a new listening address is created, these may change
//! over time as interfaces become available or unavailable.
//! For example in case of our TCP transport, it may (among others) listen on the
//! loopback interface (localhost) `/ip4/127.0.0.1/tcp/24915` as well as the local
//! network `/ip4/192.168.178.25tcp/24915`.
//!
//! In addition, if provided on the CLI, let's instruct our local node to dial a
//! remote peer.
//!
//! ```rust
//! use libp2p::{identity, Multiaddr, PeerId};
//! use libp2p::ping::{Ping, PingConfig};
//! use libp2p::swarm::{Swarm, dial_opts::DialOpts};
//! use std::error::Error;
//!
//! #[async_std::main]
//! async fn main() -> Result<(), Box<dyn Error>> {
//! let local_key = identity::Keypair::generate_ed25519();
//! let local_peer_id = PeerId::from(local_key.public());
//! println!("Local peer id: {:?}", local_peer_id);
//!
//! let transport = libp2p::development_transport(local_key).await?;
//!
//! // Create a ping network behaviour.
//! //
//! // For illustrative purposes, the ping protocol is configured to
//! // keep the connection alive, so a continuous sequence of pings
//! // can be observed.
//! let behaviour = Ping::new(PingConfig::new().with_keep_alive(true));
//!
//! let mut swarm = Swarm::new(transport, behaviour, local_peer_id);
//!
//! // Tell the swarm to listen on all interfaces and a random, OS-assigned
//! // port.
//! swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;
//!
//! // Dial the peer identified by the multi-address given as the second
//! // command-line argument, if any.
//! if let Some(addr) = std::env::args().nth(1) {
//! let remote: Multiaddr = addr.parse()?;
//! swarm.dial(remote)?;
//! println!("Dialed {}", addr)
//! }
//!
//! Ok(())
//! }
//! ```
//!
//! ## Continuously polling the Swarm
//!
//! We have everything in place now. The last step is to drive the [`Swarm`] in
//! a loop, allowing it to listen for incoming connections and establish an
//! outgoing connection in case we specify an address on the CLI.
//!
//! ```no_run
//! use futures::prelude::*;
//! use libp2p::ping::{Ping, PingConfig};
//! use libp2p::swarm::{Swarm, SwarmEvent, dial_opts::DialOpts};
//! use libp2p::{identity, Multiaddr, PeerId};
//! use std::error::Error;
//!
//! #[async_std::main]
//! async fn main() -> Result<(), Box<dyn Error>> {
//! let local_key = identity::Keypair::generate_ed25519();
//! let local_peer_id = PeerId::from(local_key.public());
//! println!("Local peer id: {:?}", local_peer_id);
//!
//! let transport = libp2p::development_transport(local_key).await?;
//!
//! // Create a ping network behaviour.
//! //
//! // For illustrative purposes, the ping protocol is configured to
//! // keep the connection alive, so a continuous sequence of pings
//! // can be observed.
//! let behaviour = Ping::new(PingConfig::new().with_keep_alive(true));
//!
//! let mut swarm = Swarm::new(transport, behaviour, local_peer_id);
//!
//! // Tell the swarm to listen on all interfaces and a random, OS-assigned
//! // port.
//! swarm.listen_on("/ip4/0.0.0.0/tcp/0".parse()?)?;
//!
//! // Dial the peer identified by the multi-address given as the second
//! // command-line argument, if any.
//! if let Some(addr) = std::env::args().nth(1) {
//! let remote: Multiaddr = addr.parse()?;
//! swarm.dial(remote)?;
//! println!("Dialed {}", addr)
//! }
//!
//! loop {
//! match swarm.select_next_some().await {
//! SwarmEvent::NewListenAddr { address, .. } => println!("Listening on {:?}", address),
//! SwarmEvent::Behaviour(event) => println!("{:?}", event),
//! _ => {}
//! }
//! }
//!
//! }
//! ```
//!
//! ## Running two nodes
//!
//! For convenience the example created above is also implemented in full in
//! `examples/ping.rs`. Thus, you can either run the commands below from your
//! own project created during the tutorial, or from the root of the rust-libp2p
//! repository. Note that in the former case you need to ignore the `--example
//! ping` argument.
//!
//! You need two terminals. In the first terminal window run:
//!
//! ```sh
//! cargo run --example ping
//! ```
//!
//! It will print the PeerId and the new listening addresses, e.g.
//! ```sh
//! Local peer id: PeerId("12D3KooWT1As4mwh3KYBnNTw9bSrRbYQGJTm9SSte82JSumqgCQG")
//! Listening on "/ip4/127.0.0.1/tcp/24915"
//! Listening on "/ip4/192.168.178.25/tcp/24915"
//! Listening on "/ip4/172.17.0.1/tcp/24915"
//! Listening on "/ip6/::1/tcp/24915"
//! ```
//!
//! In the second terminal window, start a new instance of the example with:
//!
//! ```sh
//! cargo run --example ping -- /ip4/127.0.0.1/tcp/24915
//! ```
//!
//! Note: The [`Multiaddr`] at the end being one of the [`Multiaddr`] printed
//! earlier in terminal window one.
//! Both peers have to be in the same network with which the address is associated.
//! In our case any printed addresses can be used, as both peers run on the same
//! device.
//!
//! The two nodes will establish a connection and send each other ping and pong
//! messages every 15 seconds.
//!
//! [`Multiaddr`]: crate::core::Multiaddr
//! [`NetworkBehaviour`]: crate::swarm::NetworkBehaviour
//! [`Transport`]: crate::core::Transport
//! [`PeerId`]: crate::core::PeerId
//! [`Swarm`]: crate::swarm::Swarm
//! [`development_transport`]: crate::development_transport