From ceb4787ec8d5847077c8542125e21c38d3029bb0 Mon Sep 17 00:00:00 2001 From: Kaloyan Tanev Date: Thu, 23 May 2024 17:03:25 +0300 Subject: [PATCH 1/6] Add network tests in advanced docs --- docs/advanced/test-command.md | 91 +++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/advanced/test-command.md diff --git a/docs/advanced/test-command.md b/docs/advanced/test-command.md new file mode 100644 index 0000000000..c46709b545 --- /dev/null +++ b/docs/advanced/test-command.md @@ -0,0 +1,91 @@ +--- +sidebar_position: 1 +description: Test networking between Charon dependant services +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Network tests + +:::caution +The charon test command is in alpha state and should be used with caution on testnets only. +::: + +Charon test command is evaluates effectiveness of the network between the machine it is running on and the targeted external service - other Charon peers, beacon node(s) or validator client. It prints a performance report to the standard output (can be omitted by with `quiet` flag) and a machine-readable TOML format of the report if `output-toml` flag is set. + +## Peers + +Run tests towards other Charon peers to evaluate the effectiveness of a potential cluster setup. The command sets up a libp2p node, similarly to what Charon originally does. This test command **has to be running simultanuously with other peers**. After the node is up it has some await time for other peers to get their nodes up and running, retrying every 3 seconds. The libp2p node connects to relays (configurable with `p2p-relays` flag) and to other libp2p nodes via TCP. Other peer nodes are discoverable by using their ENRs. Note that for a peer to be successfully discovered, it needs to be connected to the same relay. After completion of the test suite the libp2p node stays alive (duration configurable with `keep-alive` flag) for other peers to continue testing against it. The node can be forcefully stopped as well. + +To be able to establish direct connection, you have to ensure: + +- Your machine is publicly accessible on the internet or atleast a specific port is. +- You add flag `p2p-tcp-address` (i.e.: `127.0.0.1:9001`) flag and the port specified in it is free and publicly accessible. +- You add the flag `p2p-external-ip` (i.e.: `8.8.8.8`) and specify your public ip. + +If all points are satisfied by you and the other peers, you should be able to establish a direct TCP connection between each other. Note that a relay is still required, as establishing direct connection is facilitated by it. + +### Pre-requisites + +- [Create ENR](http://localhost:3000/docs/next/charon/charon-cli-reference#creating-an-enr-for-charon). +- Share your ENR with other peers which will test against you. +- Obtain the ENRs of the other peers against which you will test. + +### Run + +```shell +charon alpha test peers \ + --enrs="enr:-HW4QNDXi9MzdH9Af65g20jDfelAJ0kJhclitkYYgFziYHXhRFF6JyB_CnVnimB7VxKBGBSkHbmy-Tu8BJq8JQkfptiAgmlkgnY0iXNlY3AyNTZrMaEDBVt5pk6x0A2fjth25pjLOEE9DpqCG-BCYyvutY04TZ,enr:-HW4QO2vefLueTBEUGly5hkcpL7NWdMKWx7Nuy9f7z6XZInCbFAc0IZj6bsnmj-Wi4ElS6jNa0Mge5Rkc2WGTVemas2AgmlkgnY0iXNlY3AyNTZrMaECR9SmYQ_1HRgJmNxvh_ER2Sxx78HgKKgKaOkCROYwaDY" +``` + +### Run with Docker + +```shell +docker run -v /Users/obol/charon/.charon:/opt/charon/.charon obolnetwork/charon:v1.0.0-rc1 alpha test peers \ + --enrs="enr:-HW4QNDXi9MzdH9Af65g20jDfelAJ0kJhclitkYYgFziYHXhRFF6JyB_CnVnimB7VxKBGBSkHbmy-Tu8BJq8JQkfptiAgmlkgnY0iXNlY3AyNTZrMaEDBVt5pk6x0A2fjth25pjLOEE9DpqCG-BCYyvutY04TZs,enr:-HW4QO2vefLueTBEUGly5hkcpL7NWdMKWx7Nuy9f7z6XZInCbFAc0IZj6bsnmj-Wi4ElS6jNa0Mge5Rkc2WGTVemas2AgmlkgnY0iXNlY3AyNTZrMaECR9SmYQ_1HRgJmNxvh_ER2Sxx78HgKKgKaOkCROYwaDY" +``` + +## Beacon + +Run tests towards beacon node(s), evaluating the effectiveness of a potential connection of a Charon node running on the same machine. + +### Pre-requisites + +- Running beacon node(s) towards which tests will be executed. + +### Run + +```shell +charon alpha test beacon \ + --endpoints="https://ethereum-holesky-beacon-api.publicnode.com,https://ethereum-sepolia-beacon-api.publicnode.com" +``` + +### Run with Docker + +```shell +docker run obolnetwork/charon:v1.0.0-rc1 alpha test beacon \ + --endpoints="https://ethereum-holesky-beacon-api.publicnode.com,https://ethereum-sepolia-beacon-api.publicnode.com" +``` + +## Validator + +Run tests towards a validator client, evaluating the effectiveness of a potential connection of a Charon node running on the same machine. + +The default endpoint for pinging a validator client is set to `127.0.0.1:3600` (configurable with `validator-api-address` flag). + +### Pre-requisites + +- Running validator client towards which tests will be executed. + +### Run + +```shell +charon alpha test validator +``` + +### Run with Docker + +```shell +docker run obolnetwork/charon:v1.0.0-rc1 alpha test validator +``` From 93e6a9526af8c953797b682f37b2e263a5dcb367 Mon Sep 17 00:00:00 2001 From: Kaloyan Tanev <24719519+KaloyanTanev@users.noreply.github.com> Date: Fri, 24 May 2024 17:19:32 +0200 Subject: [PATCH 2/6] Reword general test command description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gianguido Sorà --- docs/advanced/test-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/test-command.md b/docs/advanced/test-command.md index c46709b545..60621e2a9c 100644 --- a/docs/advanced/test-command.md +++ b/docs/advanced/test-command.md @@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem'; The charon test command is in alpha state and should be used with caution on testnets only. ::: -Charon test command is evaluates effectiveness of the network between the machine it is running on and the targeted external service - other Charon peers, beacon node(s) or validator client. It prints a performance report to the standard output (can be omitted by with `quiet` flag) and a machine-readable TOML format of the report if `output-toml` flag is set. +Charon test command evaluates network performance and effectiveness of the machine it is running on and the targeted external service - other Charon peers, beacon node(s) or validator client. It prints a performance report to the standard output (can be omitted by with `quiet` flag) and a machine-readable TOML format of the report if `output-toml` flag is set. ## Peers From 17599dce7f5afa4535f02accb07dd8100d9891b2 Mon Sep 17 00:00:00 2001 From: Kaloyan Tanev <24719519+KaloyanTanev@users.noreply.github.com> Date: Fri, 24 May 2024 17:20:04 +0200 Subject: [PATCH 3/6] Reword and fix typos in peers test description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gianguido Sorà --- docs/advanced/test-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/test-command.md b/docs/advanced/test-command.md index 60621e2a9c..6e9cd2835f 100644 --- a/docs/advanced/test-command.md +++ b/docs/advanced/test-command.md @@ -16,7 +16,7 @@ Charon test command evaluates network performance and effectiveness of the machi ## Peers -Run tests towards other Charon peers to evaluate the effectiveness of a potential cluster setup. The command sets up a libp2p node, similarly to what Charon originally does. This test command **has to be running simultanuously with other peers**. After the node is up it has some await time for other peers to get their nodes up and running, retrying every 3 seconds. The libp2p node connects to relays (configurable with `p2p-relays` flag) and to other libp2p nodes via TCP. Other peer nodes are discoverable by using their ENRs. Note that for a peer to be successfully discovered, it needs to be connected to the same relay. After completion of the test suite the libp2p node stays alive (duration configurable with `keep-alive` flag) for other peers to continue testing against it. The node can be forcefully stopped as well. +Run tests towards other Charon peers to evaluate the effectiveness of a potential cluster setup. The command sets up a libp2p node, similarly to what Charon originally does. This test command **has to be running simultaneously with other peers**. After the node is up it waits for other peers to get their nodes up and running, retrying connection every 3 seconds. The libp2p node connects to relays (configurable with `p2p-relays` flag) and to other libp2p nodes via TCP. Other peer nodes are discoverable by using their ENRs. Note that for a peer to be successfully discovered, it needs to be connected to the same relay. After completion of the test suite the libp2p node stays alive (duration configurable with `keep-alive` flag) for other peers to continue testing against it. The node can be forcefully stopped as well. To be able to establish direct connection, you have to ensure: From b365b0825ce10c42b30b33aa9c102bcc349229e3 Mon Sep 17 00:00:00 2001 From: Kaloyan Tanev <24719519+KaloyanTanev@users.noreply.github.com> Date: Fri, 24 May 2024 17:23:51 +0200 Subject: [PATCH 4/6] Reword peers direct connection description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gianguido Sorà --- docs/advanced/test-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/test-command.md b/docs/advanced/test-command.md index 6e9cd2835f..e4960ec70e 100644 --- a/docs/advanced/test-command.md +++ b/docs/advanced/test-command.md @@ -24,7 +24,7 @@ To be able to establish direct connection, you have to ensure: - You add flag `p2p-tcp-address` (i.e.: `127.0.0.1:9001`) flag and the port specified in it is free and publicly accessible. - You add the flag `p2p-external-ip` (i.e.: `8.8.8.8`) and specify your public ip. -If all points are satisfied by you and the other peers, you should be able to establish a direct TCP connection between each other. Note that a relay is still required, as establishing direct connection is facilitated by it. +If all points are satisfied by you and the other peers, you should be able to establish a direct TCP connection between each other. Note that a relay is still required, as it is used for peer discovery. ### Pre-requisites From 08deffd0734b5d90c766c6c6b0af62ae12994c3f Mon Sep 17 00:00:00 2001 From: Kaloyan Tanev Date: Fri, 24 May 2024 18:31:41 +0300 Subject: [PATCH 5/6] Change path to relative and fix typo --- docs/advanced/test-command.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/test-command.md b/docs/advanced/test-command.md index e4960ec70e..4249bb2421 100644 --- a/docs/advanced/test-command.md +++ b/docs/advanced/test-command.md @@ -20,7 +20,7 @@ Run tests towards other Charon peers to evaluate the effectiveness of a potentia To be able to establish direct connection, you have to ensure: -- Your machine is publicly accessible on the internet or atleast a specific port is. +- Your machine is publicly accessible on the internet or at least a specific port is. - You add flag `p2p-tcp-address` (i.e.: `127.0.0.1:9001`) flag and the port specified in it is free and publicly accessible. - You add the flag `p2p-external-ip` (i.e.: `8.8.8.8`) and specify your public ip. @@ -28,7 +28,7 @@ If all points are satisfied by you and the other peers, you should be able to es ### Pre-requisites -- [Create ENR](http://localhost:3000/docs/next/charon/charon-cli-reference#creating-an-enr-for-charon). +- [Create ENR](../charon/charon-cli-reference#creating-an-enr-for-charon). - Share your ENR with other peers which will test against you. - Obtain the ENRs of the other peers against which you will test. From 0936ffad0c7cc93f9c295578e4f3457e05d34883 Mon Sep 17 00:00:00 2001 From: Kaloyan Tanev Date: Mon, 27 May 2024 22:24:31 +0300 Subject: [PATCH 6/6] Change caution message to be less harsh --- docs/advanced/test-command.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/test-command.md b/docs/advanced/test-command.md index 4249bb2421..6ddf51e59b 100644 --- a/docs/advanced/test-command.md +++ b/docs/advanced/test-command.md @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; # Network tests :::caution -The charon test command is in alpha state and should be used with caution on testnets only. +The charon test command is in alpha state and is still in development. It can not do any harm, but there is no guarantee it is stable and working as expected. ::: Charon test command evaluates network performance and effectiveness of the machine it is running on and the targeted external service - other Charon peers, beacon node(s) or validator client. It prints a performance report to the standard output (can be omitted by with `quiet` flag) and a machine-readable TOML format of the report if `output-toml` flag is set.