From f2921ad42e3b89cb01b37cfa61b2d171868899bd Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Mon, 10 Jan 2022 00:02:33 -0800 Subject: [PATCH 1/2] Improve discovery docs Signed-off-by: Alexandra Tran --- docs/HowTo/Find-and-Connect/Bootnodes.md | 2 +- docs/HowTo/Find-and-Connect/Managing-Peers.md | 99 +++++++++++-------- docs/Reference/CLI/CLI-Syntax.md | 4 +- 3 files changed, 62 insertions(+), 43 deletions(-) diff --git a/docs/HowTo/Find-and-Connect/Bootnodes.md b/docs/HowTo/Find-and-Connect/Bootnodes.md index 7ff0f70b074..1866541c0e4 100644 --- a/docs/HowTo/Find-and-Connect/Bootnodes.md +++ b/docs/HowTo/Find-and-Connect/Bootnodes.md @@ -4,7 +4,7 @@ description: Configuring bootnodoes # Bootnodes -Using Bootnodes is a method for initially discovering peers. Bootnodes are regular nodes used to +Using bootnodes is a method for initially discovering peers. Bootnodes are regular nodes used to discover other nodes. !!! tip diff --git a/docs/HowTo/Find-and-Connect/Managing-Peers.md b/docs/HowTo/Find-and-Connect/Managing-Peers.md index 1159d172391..faaba9b6eb2 100644 --- a/docs/HowTo/Find-and-Connect/Managing-Peers.md +++ b/docs/HowTo/Find-and-Connect/Managing-Peers.md @@ -2,72 +2,91 @@ description: Managing Hyperledger Besu peers --- -# Managing peers +# Manage peers -## Limiting peers +Hyperledger Besu peer-to-peer (P2P) discovery happens periodically based on the number of peers in a network and the +node's [peer limit](#limit-peers). -Limiting peers reduces the bandwidth used by Hyperledger Besu. Limiting peers also reduces the CPU +The frequency of discovery isn't configurable, but you can [limit remote connections](#limit-remote-connections) in +public networks and [randomly prioritize connections](../../Reference/CLI/CLI-Syntax.md#random-peer-priority-enabled) +in small, stable networks. + +!!! info + + You can use [`admin_addPeer`](../../Reference/API-Methods.md#admin_addpeer) to attempt a specific connection, but + this isn't P2P discovery. + +We recommend [using bootnodes](Bootnodes.md) to initially discover peers. + +## Limit peers + +Limiting peers reduces the bandwidth used by Besu. Limiting peers also reduces the CPU time and disk access used to manage and respond to peers. To reduce the maximum number of peers, use the [`--max-peers`](../../Reference/CLI/CLI-Syntax.md#max-peers) option. The default is 25. -## No discovery +## Limit remote connections -To disable P2P discovery, use the -[`--discovery-enabled`](../../Reference/CLI/CLI-Syntax.md#discovery-enabled) option. +In public networks, enabling the [remote connection limits](../../Reference/CLI/CLI-Syntax.md#remote-connections-limit-enabled) +is necessary to prevent eclipse attacks, especially when using [`--sync-mode`](../../Reference/CLI/CLI-Syntax.md#sync-mode) +and [`--fast-sync-min-peers`](../../Reference/CLI/CLI-Syntax.md#fast-sync-min-peers). -With discovery disabled, peers that have already discovered or are otherwise configured to connect -to the local node (for example, using -[`admin_addPeer`](../../Reference/API-Methods.md#admin_addpeer)) can open connections. -[Static nodes](Static-Nodes.md) can also open connections. +In private and permissioned networks with a level of trust between peers, enabling the remote connection limits is +unnecessary and might adversely affect the speed at which nodes can join the network. +Limiting remote connections may cause a clique of nodes to form when the number of nodes in the network is slightly +higher than [`--max-peers`](../../Reference/CLI/CLI-Syntax.md#max-peers). +The nodes in this clique are all connected to each other and can't accept more connections. + +!!! tip + + You can use [`--random-peer-priority-enabled`](../../Reference/CLI/CLI-Syntax.md#random-peer-priority-enabled) to + help prevent cliques in small, stable networks. -## Monitoring peer connections +## Monitor peer connections JSON-RPC API methods to monitor peer connections include: -* [`net_peerCount`](../../Reference/API-Methods.md#net_peercount) -* [`admin_peers`](../../Reference/API-Methods.md#admin_peers) +* [`net_peerCount`](../../Reference/API-Methods.md#net_peercount). +* [`admin_peers`](../../Reference/API-Methods.md#admin_peers). * [`debug_metrics`](../../Reference/API-Methods.md#debug_metrics). Each peer entry returned by [`admin_peers`](../../Reference/API-Methods.md#admin_peers) includes a `protocols` section. Use the information in the `protocols` section to: -* Determine health of peers. For example, an external process could use [`admin_peers`](../../Reference/API-Methods.md#admin_peers) -and [`admin_removePeer`](../../Reference/API-Methods.md#admin_removepeer) to disconnect from peers that -are stalled at a single difficulty for an extended period of time. +* Determine the health of peers. + For example, an external process can use [`admin_peers`](../../Reference/API-Methods.md#admin_peers) and + [`admin_removePeer`](../../Reference/API-Methods.md#admin_removepeer) to disconnect from peers that are stalled at a + single difficulty for an extended period of time. -* Monitor node health. For example, if peers are reporting increasing difficulties but node -is stuck at the same block number, the node may be on a different fork to most peers. +* Monitor node health. + For example, if peers report increasing difficulties but the node is stuck at the same block number, the node may be + on a different fork to most peers. -* Determine which protocol level peers are communicating with. For example, to see if `"version": 65` -is being used to reduce transaction sharing traffic. +* Determine which protocol level peers are communicating with. + For example, you can see if `"version": 65` is being used to reduce transaction sharing traffic. -## Node connections +## List node connections -The default logging configuration does not list node connection and disconnection messages. +The default logging configuration doesn't list node connection and disconnection messages. +To enable listing them, set the [`--logging`](../../Reference/CLI/CLI-Syntax.md#logging) option to `DEBUG`. +For more verbosity, set the option to `TRACE`. -To enable listing of node connection and disconnection messages, specify the -[`--logging`](../../Reference/CLI/CLI-Syntax.md#logging) option `--logging=DEBUG`. For more -verbosity, specify `--logging=TRACE`. - -The console logs connection and disconnection events when the log level is `DEBUG` or higher. If -the message `Successfully accepted connection from ...` displays, connections are getting through -the firewalls. +The console logs connection and disconnection events when the log level is `DEBUG` or higher. +If the message `Successfully accepted connection from ...` displays, connections are getting through the firewalls. !!! example "Sample log output" - `2018-10-16 12:37:35.479-04:00 | nioEventLoopGroup-3-1 | INFO | NettyP2PNetwork | Successfully accepted connection from 0xa979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c` + ```bash + 2018-10-16 12:37:35.479-04:00 | nioEventLoopGroup-3-1 | INFO | NettyP2PNetwork | Successfully accepted connection from 0xa979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c + ``` -## Limiting remote connections +## Disable discovery -In private and permissioned networks with a level of trust between peers, enabling the -[remote connection limits](../../Reference/CLI/CLI-Syntax.md#remote-connections-limit-enabled) -is unnecessary and might adversely affect the speed at which nodes can join the network. -Limiting remote connections may cause a clique of nodes to form when the number of nodes in the network is slightly -higher than [`--max-peers`](../../Reference/CLI/CLI-Syntax.md#max-peers). -The nodes in this clique are all connected to each other and cannot accept more connections. +To disable P2P discovery, set the +[`--discovery-enabled`](../../Reference/CLI/CLI-Syntax.md#discovery-enabled) option to `false`. -In public networks, enabling the remote connections limit is necessary to prevent eclipse attacks, especially when -using [`--sync-mode`](../../Reference/CLI/CLI-Syntax.md#sync-mode) and -[`--fast-sync-min-peers`](../../Reference/CLI/CLI-Syntax.md#fast-sync-min-peers). +With discovery disabled, peers that have already discovered or are otherwise configured to connect +to the local node (for example, using +[`admin_addPeer`](../../Reference/API-Methods.md#admin_addpeer)) can open connections. +[Static nodes](Static-Nodes.md) can also open connections. diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md index 99cfee84170..294d49c9c40 100644 --- a/docs/Reference/CLI/CLI-Syntax.md +++ b/docs/Reference/CLI/CLI-Syntax.md @@ -2390,8 +2390,8 @@ impenetrable peer groups forming. The default is `false`. remote-connections-limit-enabled=false ``` -Enables or disables limiting the percentage of remote P2P connections initiated by peers. The -default is true. +Enables or disables [limiting the percentage of remote P2P connections initiated by peers](#remote-connections-max-percentage). +The default is `true`. !!! tip From 37e65a68703cd53b01df26b732253f62e1a4f7ae Mon Sep 17 00:00:00 2001 From: Alexandra Tran Date: Wed, 12 Jan 2022 11:33:39 -0800 Subject: [PATCH 2/2] integrate reviewer feedback Signed-off-by: Alexandra Tran --- docs/HowTo/Find-and-Connect/Bootnodes.md | 4 ++-- docs/HowTo/Find-and-Connect/Managing-Peers.md | 24 +++++++++---------- docs/Reference/CLI/CLI-Syntax.md | 5 ++-- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/HowTo/Find-and-Connect/Bootnodes.md b/docs/HowTo/Find-and-Connect/Bootnodes.md index 1866541c0e4..ab0980f9157 100644 --- a/docs/HowTo/Find-and-Connect/Bootnodes.md +++ b/docs/HowTo/Find-and-Connect/Bootnodes.md @@ -4,8 +4,8 @@ description: Configuring bootnodoes # Bootnodes -Using bootnodes is a method for initially discovering peers. Bootnodes are regular nodes used to -discover other nodes. +You can use bootnodes to initially discover peers. +Bootnodes are regular nodes used to discover other nodes. !!! tip diff --git a/docs/HowTo/Find-and-Connect/Managing-Peers.md b/docs/HowTo/Find-and-Connect/Managing-Peers.md index faaba9b6eb2..4bb501297a5 100644 --- a/docs/HowTo/Find-and-Connect/Managing-Peers.md +++ b/docs/HowTo/Find-and-Connect/Managing-Peers.md @@ -20,28 +20,27 @@ We recommend [using bootnodes](Bootnodes.md) to initially discover peers. ## Limit peers -Limiting peers reduces the bandwidth used by Besu. Limiting peers also reduces the CPU -time and disk access used to manage and respond to peers. +You can limit peers to reduce the bandwidth, CPU time, and disk access Besu uses to manage and respond to peers. To reduce the maximum number of peers, use the [`--max-peers`](../../Reference/CLI/CLI-Syntax.md#max-peers) option. The default is 25. ## Limit remote connections -In public networks, enabling the [remote connection limits](../../Reference/CLI/CLI-Syntax.md#remote-connections-limit-enabled) -is necessary to prevent eclipse attacks, especially when using [`--sync-mode`](../../Reference/CLI/CLI-Syntax.md#sync-mode) -and [`--fast-sync-min-peers`](../../Reference/CLI/CLI-Syntax.md#fast-sync-min-peers). +Prevent eclipse attacks when using [`--sync-mode`](../../Reference/CLI/CLI-Syntax.md#sync-mode) and +[`--fast-sync-min-peers`](../../Reference/CLI/CLI-Syntax.md#fast-sync-min-peers) on public networks by enabling the +[remote connection limits](../../Reference/CLI/CLI-Syntax.md#remote-connections-limit-enabled). -In private and permissioned networks with a level of trust between peers, enabling the remote connection limits is +In private and permissioned networks with only trusted peers, enabling the remote connection limits is unnecessary and might adversely affect the speed at which nodes can join the network. -Limiting remote connections may cause a clique of nodes to form when the number of nodes in the network is slightly -higher than [`--max-peers`](../../Reference/CLI/CLI-Syntax.md#max-peers). -The nodes in this clique are all connected to each other and can't accept more connections. +Limiting remote connections can cause a closed group of peers to form when the number of nodes in the network is +slightly higher than [`--max-peers`](../../Reference/CLI/CLI-Syntax.md#max-peers). +The nodes in this closed group are all connected to each other and can't accept more connections. !!! tip You can use [`--random-peer-priority-enabled`](../../Reference/CLI/CLI-Syntax.md#random-peer-priority-enabled) to - help prevent cliques in small, stable networks. + help prevent closed groups of peers in small, stable networks. ## Monitor peer connections @@ -86,7 +85,6 @@ If the message `Successfully accepted connection from ...` displays, connections To disable P2P discovery, set the [`--discovery-enabled`](../../Reference/CLI/CLI-Syntax.md#discovery-enabled) option to `false`. -With discovery disabled, peers that have already discovered or are otherwise configured to connect -to the local node (for example, using -[`admin_addPeer`](../../Reference/API-Methods.md#admin_addpeer)) can open connections. +With discovery disabled, peers can't open connections with the node unless they were previously discovered or manually +peered (for example, using [`admin_addPeer`](../../Reference/API-Methods.md#admin_addpeer)). [Static nodes](Static-Nodes.md) can also open connections. diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md index 294d49c9c40..62190945b30 100644 --- a/docs/Reference/CLI/CLI-Syntax.md +++ b/docs/Reference/CLI/CLI-Syntax.md @@ -2362,7 +2362,7 @@ Defaults to `false`. ``` Allows for incoming connections to be prioritized randomly. Enable in small, stable networks to prevent -impenetrable peer groups forming. The default is `false`. +closed groups of peers forming. The default is `false`. ### `remote-connections-limit-enabled` @@ -2390,7 +2390,8 @@ impenetrable peer groups forming. The default is `false`. remote-connections-limit-enabled=false ``` -Enables or disables [limiting the percentage of remote P2P connections initiated by peers](#remote-connections-max-percentage). +Enables or disables using the [`--remote-connections-max-percentage`](#remote-connections-max-percentage) option to +limit the percentage of remote P2P connections initiated by peers. The default is `true`. !!! tip