From c27a90b8588e9f2be8c75d8e384682aae5a001df Mon Sep 17 00:00:00 2001 From: sig Date: Sat, 3 Oct 2020 09:28:13 +0100 Subject: [PATCH 1/8] fix bug --- docs/installation/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation/configuration.md b/docs/installation/configuration.md index b8aba2c27..a18e02863 100644 --- a/docs/installation/configuration.md +++ b/docs/installation/configuration.md @@ -1,4 +1,4 @@ -\--- +--- title: Configuring Your Bee Node id: configuration --- From 74f1ab68dbe262ddb303373aed9033f275a16c5b Mon Sep 17 00:00:00 2001 From: sig Date: Sat, 3 Oct 2020 09:32:29 +0100 Subject: [PATCH 2/8] bump version --- README.md | 3 +++ docs/installation/build-from-source.md | 2 +- docs/installation/docker.md | 2 +- docs/installation/quick-start.md | 6 +++--- 4 files changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 60dde63c8..1dca9154b 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,9 @@ $ npm run build This command generates static content into the `build` directory and can be served using any static contents hosting service. +## Bumping Version + +Don't forget to find and replace the version number for the whole of the docs folder. ## How to generate / include the API reference html diff --git a/docs/installation/build-from-source.md b/docs/installation/build-from-source.md index da9e43005..7ef2e22f4 100644 --- a/docs/installation/build-from-source.md +++ b/docs/installation/build-from-source.md @@ -41,7 +41,7 @@ make binary 5) Check you are able to run the `bee` command. Success can be verified by running: ```sh dist/bee version -> 0.2.0 +> 0.3.0 ``` 6) (optional) Additionally, you may also like to move the Bee binary to somewhere in your `$PATH` diff --git a/docs/installation/docker.md b/docs/installation/docker.md index b7f7ca85c..8e0b4f30f 100644 --- a/docs/installation/docker.md +++ b/docs/installation/docker.md @@ -48,7 +48,7 @@ docker pull ethersphere/bee:alpha #### Specific Versions ```sh -docker pull ethersphere/bee:0.2.0 +docker pull ethersphere/bee:0.3.0 ``` #### Edge diff --git a/docs/installation/quick-start.md b/docs/installation/quick-start.md index 6e2d3fa52..66c5afb82 100644 --- a/docs/installation/quick-start.md +++ b/docs/installation/quick-start.md @@ -15,12 +15,12 @@ Simply run either one of the following commands in your Terminal... #### wget ```sh -wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v0.2.0 bash +wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v0.3.0 bash ``` #### curl ```sh -curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v0.2.0 bash +curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | TAG=v0.3.0 bash ``` ### Run Bee @@ -29,7 +29,7 @@ Once you have installed Bee, you can test that it has been successfully installe ```sh bee version -> 0.2.0 +> 0.3.0 ``` ### Upgrading Bee From 610f94e339414be2575165bdf7446ebb7f18533f Mon Sep 17 00:00:00 2001 From: sig Date: Sat, 3 Oct 2020 10:00:44 +0100 Subject: [PATCH 3/8] improve PSS docs --- docs/advanced/pss.md | 101 ++++++++++++++++++++++++++----------------- 1 file changed, 62 insertions(+), 39 deletions(-) diff --git a/docs/advanced/pss.md b/docs/advanced/pss.md index 893ba7b5d..e5b3706b1 100644 --- a/docs/advanced/pss.md +++ b/docs/advanced/pss.md @@ -7,14 +7,6 @@ Out of the ashes of Ethereum's vision for a leak-proof decentralised anonymous m PSS provides a pub-sub facility that can be used for a variety of tasks. Nodes are able to listen to messages received for a specific topic in their nearest neighbourhood and create messages destined for another neighbourhood which are sent over the network using Swarm's usual data dissemination protocols. -### Enable PSS On Your Node - -In order to receive PSS messages you must first enable the p2p websockets API when starting your node. - -```sh - bee start --p2p-ws-enable -``` - ### Subscribe and Receive Messages Once your Bee node is up and running, you will be able to subscribe to feeds using websockets. For testing, it is useful to use the [websocat](https://docs.rs/crate/websocat/1.0.1) command line utility. @@ -31,21 +23,31 @@ Our node is now watching for new messages received in it's nearest neighbourhood Messages can be sent simply by sending a `POST` request to the PSS api endpoint. -When sending messages, we must specify a 'target' prefix of the recipients swarm address, a partial address representing their neighbourhood. Currently the length of this prefix is recommended to be two bytes, which will work well until the network has grown to a size of ca. 20-50K nodes. +When sending messages, we must specify a 'target' prefix of the recipients swarm address, a partial address representing their neighbourhood. Currently the length of this prefix is recommended to be two bytes, which will work well until the network has grown to a size of ca. 20-50K nodes. We must also provide the public key, so that Bee can encrypt the message in such a way that it may only be read by the intended recipient. + +For example, if we want to send a PSS message with **topic** `test-topic` to a node with address... + +`7bc50a5d79cb69fa5a0df519c6cc7b420034faaa61c175b88fc4c683f7c79d96` -For example, if we want to send a PSS message to a node with address `49d80b28adccd67a09959a601f0e28521aaeb06bf1bf17e9e012e7b597c3d926`, we must include the 'target' `49d8`. +...and public key... + +`0349f7b9a6fa41b3a123c64706a072014d27f56accd9a0e92b06fe8516e470d8dd` + +...we must include the **target** `7bc5` and the public key itself as a query argument. ```sh -curl -XPOST localhost:8082/pss/send/test/49d8 --data "Hello Swarm" +curl -XPOST \ +localhost:8082/pss/send/test/7bc5?recipient=0349f7b9a6fa41b3a123c64706a072014d27f56accd9a0e92b06fe8516e470d8dd \ +--data "Hello Swarm" ``` ### Send Messages in a Test Network -Now, let's see this in action by setting up two Bee nodes, connecting them, and sending PSS messages from one to the other. +Now, let's see this in action by setting up two Bee nodes on a test network, connecting them, and sending PSS messages from one to the other. First start two Bee nodes. We will start them with distinct ports for the api, debug api and p2p port so that there are no conflicts, since they will be running on the same computer. -Run the following command to start the first node. Note that we are passing `""` to the `--bootnode` argument so that our nodes will not connect to the network. +Run the following command to start the first node. Note that we are passing `""` to the `--bootnode` argument so that our nodes will not connect to a network. ```sh bee start \ @@ -54,12 +56,11 @@ bee start \ --debug-api-addr=:6062 \ --data-dir=/tmp/bee2 \ --bootnode="" \ - --p2p-ws-enable \ --p2p-addr=:7072 \ --swap-enable=false ``` -We must make a note of the Swarm overlay address, underlay address and public key which are created once each node has started. We find this information from the addresses endpoint of the debug API. +We must make a note of the Swarm overlay address, underlay address and public key which are created once each node has started. We find this information from the addresses endpoint of the Debug API. ```sh curl -s localhost:6062/addresses | jq @@ -67,14 +68,14 @@ curl -s localhost:6062/addresses | jq ```json { - "overlay": "c4773d0d7e8e0b7cc2145b1f9c149a0befecaf7cb2ed6eb83a32babe60a18646", + "overlay": "7bc50a5d79cb69fa5a0df519c6cc7b420034faaa61c175b88fc4c683f7c79d96", "underlay": [ - "/ip4/127.0.0.1/tcp/7072/p2p/16Uiu2HAkypRG6iEA86Vgq8xWrywcFyFHeuX9apCezcbS3cCjGtnL", - "/ip4/10.169.169.20/tcp/7072/p2p/16Uiu2HAkypRG6iEA86Vgq8xWrywcFyFHeuX9apCezcbS3cCjGtnL", - "/ip6/::1/tcp/7072/p2p/16Uiu2HAkypRG6iEA86Vgq8xWrywcFyFHeuX9apCezcbS3cCjGtnL", - "/ip4/81.98.94.4/tcp/38023/p2p/16Uiu2HAkypRG6iEA86Vgq8xWrywcFyFHeuX9apCezcbS3cCjGtnL" + "/ip4/127.0.0.1/tcp/7072/p2p/16Uiu2HAmP9i7VoEcaGtHiyB6v7HieoiB9v7GFVZcL2VkSRnFwCHr", + "/ip4/192.168.0.10/tcp/7072/p2p/16Uiu2HAmP9i7VoEcaGtHiyB6v7HieoiB9v7GFVZcL2VkSRnFwCHr", + "/ip6/::1/tcp/7072/p2p/16Uiu2HAmP9i7VoEcaGtHiyB6v7HieoiB9v7GFVZcL2VkSRnFwCHr" ], - "public_key": "02548ba0cec39e6cae23b698eeff8bebbfee45811cdcf77bc53f1f59c528d00b98" + "ethereum": "0x0000000000000000000000000000000000000000", + "public_key": "0349f7b9a6fa41b3a123c64706a072014d27f56accd9a0e92b06fe8516e470d8dd" } ``` @@ -87,32 +88,36 @@ bee start \ --debug-api-addr=:6063 \ --data-dir=/tmp/bee3 \ --bootnode="" \ - --p2p-ws-enable \ --p2p-addr=:7073 \ --swap-enable=false ``` ```sh -curl -s localhost:6062/addresses | jq +curl -s localhost:6063/addresses | jq ``` ```json { - "overlay": "c7806e676ac14f0f20aba144299146131bd33635c5b814ab993752386496b2cb", + "overlay": "a231764383d7c46c60a6571905e72021a90d506ef8db06750f8a708d93fe706e", "underlay": [ - "/ip4/127.0.0.1/tcp/7073/p2p/16Uiu2HAmVTDofiUt3BKE739m3ozsUMGuzD8mo6agADkzmrJ33uvn", - "/ip4/192.168.0.10/tcp/7073/p2p/16Uiu2HAmVTDofiUt3BKE739m3ozsUMGuzD8mo6agADkzmrJ33uvn", - "/ip6/::1/tcp/7073/p2p/16Uiu2HAmVTDofiUt3BKE739m3ozsUMGuzD8mo6agADkzmrJ33uvn", - "/ip4/81.98.94.4/tcp/20044/p2p/16Uiu2HAmVTDofiUt3BKE739m3ozsUMGuzD8mo6agADkzmrJ33uvn" + "/ip4/127.0.0.1/tcp/7073/p2p/16Uiu2HAmAqJkKJqZjNhuDtepc8eBANM9TvagaWUThfTN5NkfmKTq", + "/ip4/192.168.0.10/tcp/7073/p2p/16Uiu2HAmAqJkKJqZjNhuDtepc8eBANM9TvagaWUThfTN5NkfmKTq", + "/ip6/::1/tcp/7073/p2p/16Uiu2HAmAqJkKJqZjNhuDtepc8eBANM9TvagaWUThfTN5NkfmKTq", + "/ip4/81.98.94.4/tcp/25178/p2p/16Uiu2HAmAqJkKJqZjNhuDtepc8eBANM9TvagaWUThfTN5NkfmKTq" ], - "public_key": "034de9400e9200d7b22b9c6ff72a1d6b424c97ae4f4e151dd7ab49741db22e1310" + "ethereum": "0x0000000000000000000000000000000000000000", + "public_key": "02d68d57d9f3fe539990cdf03e7de96d56a5c68b42515bc465acec4edc5cedfe35" } ``` -Because we configured the nodes to start with no bootnodes, neither node should have any peers yet. +Because we configured the nodes to start with no bootnodes, neither node should have peers yet. + +```sh +curl -s localhost:6062/peers | jq +``` ```sh - curl -s localhost:6062/peers | jq +curl -s localhost:6063/peers | jq ``` ```json @@ -121,29 +126,46 @@ Because we configured the nodes to start with no bootnodes, neither node should } ``` -Let's connect them using the localhost (127.0.0.1) underlay address we noted earlier. +Let's connect node 2 to node 1 using the localhost (127.0.0.1) underlay address for node 1 that we have noted earlier. ```sh -curl -XPOST localhost:6062/connect/ip4/127.0.0.1/tcp/7073/p2p/16Uiu2HAmVTDofiUt3BKE739m3ozsUMGuzD8mo6agADkzmrJ33uvn +curl -XPOST \ + localhost:6063/connect/ip4/127.0.0.1/tcp/7072/p2p/16Uiu2HAmP9i7VoEcaGtHiyB6v7HieoiB9v7GFVZcL2VkSRnFwCHr ``` Now, if we check our peers endpoint for node 1, we can see our nodes are now peered together. ```sh - curl -s localhost:6062/peers | jq +curl -s localhost:6062/peers | jq +``` + +```json +{ + "peers": [ + { + "address": "a231764383d7c46c60a6571905e72021a90d506ef8db06750f8a708d93fe706e" + } + ] +} +``` + +Of course, since we are p2p, node 2 will show node 1 as a peer too. + +```sh +curl -s localhost:6063/peers | jq ``` ```json { "peers": [ { - "address": "c7806e676ac14f0f20aba144299146131bd33635c5b814ab993752386496b2cb" + "address": "7bc50a5d79cb69fa5a0df519c6cc7b420034faaa61c175b88fc4c683f7c79d96" } ] } ``` -We will use `websocat` to listen for PSS messages on a specific topic ID on our first node. +We will use `websocat` to listen for PSS messages topic ID `test-topic` on our first node. ```sh websocat ws://localhost:8082/pss/subscribe/test-topic @@ -151,12 +173,12 @@ websocat ws://localhost:8082/pss/subscribe/test-topic Now we can use PSS to send a message from our second node to our first node. -Since our first node has a 2 byte address prefix of `c477`, we will specify this as the `targets` argument in our POST request. We must also include the public key of the recipient as a query parameter so that the message can be encrypted in a way only our recipient can decrypt. +Since our first node has a 2 byte address prefix of `a231`, we will specify this as the `targets` section in our POST request's URL. We must also include the public key of the recipient as a query parameter so that the message can be encrypted in a way only our recipient can decrypt. ```sh curl \ - -XPOST "localhost:8083/pss/send/test-topic/c477?recipient=02548ba0cec39e6cae23b698eeff8bebbfee45811cdcf77bc53f1f59c528d00b98"\ - --data "Hello Swarm" + -XPOST "localhost:8083/pss/send/test-topic/7bc5?recipient=0349f7b9a6fa41b3a123c64706a072014d27f56accd9a0e92b06fe8516e470d8dd"\ + --data "Hello Swarm" ``` The PSS API endpoint will now create a PSS message for it's recipient in the form of a 'Trojan Chunk' and send this into the network so that it may be pushed to the correct neighbourhood. Once it is received by it's destination target it will be decrypted and determined to be a message with the topic we are listening for. Our second node will decrypt the data and we'll see a message pop up in our `websocat` console! @@ -166,3 +188,4 @@ sig :: ~ ยป websocat ws://localhost:8082/pss/subscribe/test-topic Hello Swarm ``` +Congratulations! ๐ŸŽ‰ You have sent your first encrypted, zero leak message over Swarm! From 5db88379cf1c684d4cd0747b67c5f528de334d2f Mon Sep 17 00:00:00 2001 From: sig Date: Mon, 5 Oct 2020 13:34:26 +0100 Subject: [PATCH 4/8] improve copy --- docs/getting-started/start-your-node.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/start-your-node.md b/docs/getting-started/start-your-node.md index 4cc882b1e..bb5c2a9ac 100644 --- a/docs/getting-started/start-your-node.md +++ b/docs/getting-started/start-your-node.md @@ -49,7 +49,7 @@ bee start \ --bootnode /dnsaddr/bootnode.staging.ethswarm.org ``` -Since we haven't yet funded our account, we will see a message in our logs asking us to fund our Ethereum account. Navigate to the [Swarm Goerli Faucet](https://faucet.ethswarm.org/) and submit your address, ensuring it is prepended with the characters `0x` to the faucet, fill out the recaptcha and wait for confirmation that your GETH and gBZZ have been dispensed. +Since we haven't yet funded our account, we will see a message in our logs asking us to fund our Ethereum account. Navigate to the [Swarm Goerli Faucet](https://faucet.ethswarm.org/) and submit your address, ensuring it is prepended with the characters `0x` to the faucet, fill out the recaptcha and wait for confirmation that your gETH and gBZZ have been dispensed. Now, we can run our Bee node and we will start to see Bee creating and waiting for transactions to complete. Please be patient as this might take a few moments. From 78b9c22f97249e1995f56b1adfec896218f5b755 Mon Sep 17 00:00:00 2001 From: sig Date: Mon, 5 Oct 2020 13:34:35 +0100 Subject: [PATCH 5/8] fix docker commands --- docs/installation/docker.md | 46 +++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/docs/installation/docker.md b/docs/installation/docker.md index 8e0b4f30f..f28e8b272 100644 --- a/docs/installation/docker.md +++ b/docs/installation/docker.md @@ -10,39 +10,61 @@ Bee is also provided as Docker images hosted at [Docker Hub](https://hub.docker. Try Bee out by simply running the following command in your Terminal. ```sh -docker run --rm -it ethersphere/bee:alpha\ - start --welcome-message="Hi I am a very buzzy bee bzzzz bzzz bzz. ๐Ÿ" +docker run\ + -v /path/to/.bee-docker:/home/bee/.bee\ + -p 6060:6060 \ + -p 7070:7070 \ + -p 8080:8080\ + --rm -it bee:v1\ + start \ + --welcome-message="Bzzzz bzzz bzz bzz. ๐Ÿ" \ + --swap-endpoint https://rpc.slock.it/goerli \ + --debug-api-enable ``` -To persist files mount a local directory as follows and enter the password used to encrypt your keyfiles. +:::info +If starting your node for the first time, you will need to deploy a chequebook contract. See [Start Your Node](/docs/getting-started/start-your-node) for more info. +::: + +To persist files mount a local directory as follows and enter the password used to encrypt your keyfiles. Note, Docker insists on absolute paths when mounting volumes, so you must replace `/path/to/.bee-docker` with a valid path from your local filesystem. ```sh docker run\ -v /path/to/.bee-docker:/home/bee/.bee\ - --rm -it ethersphere/bee:alpha\ - start + -p 6060:6060 \ + -p 7070:7070 \ + -p 8080:8080\ + --rm -it bee:v1\ + start \ + --welcome-message="Bzzzz bzzz bzz bzz. ๐Ÿ" \ + --swap-endpoint https://rpc.slock.it/goerli \ + --debug-api-enable ``` Once you have generated your keys, leave Bee to run in the background... ```sh docker run\ + -d -v /path/to/.bee-docker:/home/bee/.bee\ - -d ethersphere/bee:alpha\ - start\ - --welcome-message="Bzzzz bzzz bzz bzz. ๐Ÿ" + -p 6060:6060 \ + -p 7070:7070 \ + -p 8080:8080\ + --rm -it bee:v1\ + start \ + --welcome-message="Bzzzz bzzz bzz bzz. ๐Ÿ" \ + --swap-endpoint https://rpc.slock.it/goerli \ + --debug-api-enable ``` -Note, Docker insists on absolute paths when mounting volumes, so you must replace `/path/to/.bee-docker` with a valid path from your local filesystem. - ### Versions You other versions of the Bee container are also available. -#### Latest Alpha Release +#### Latest beta Release ```sh -docker pull ethersphere/bee:alpha +docker pull ethersphere/bee:beta ``` #### Specific Versions From 36338660809646cd663828b692f76bc917ed48e4 Mon Sep 17 00:00:00 2001 From: sig Date: Mon, 5 Oct 2020 13:34:44 +0100 Subject: [PATCH 6/8] be more friendly --- docs/installation/quick-start.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/installation/quick-start.md b/docs/installation/quick-start.md index 66c5afb82..271370a7f 100644 --- a/docs/installation/quick-start.md +++ b/docs/installation/quick-start.md @@ -48,4 +48,6 @@ wget -q -O - https://raw.githubusercontent.com/ethersphere/bee/master/install.sh #### curl ```sh curl -s https://raw.githubusercontent.com/ethersphere/bee/master/install.sh | bash -``` \ No newline at end of file +``` + +Now your Bee node is running, [get your node started](/docs/getting-started/start-your-node) and join us in the swarm! ๐Ÿ ๐Ÿ ๐Ÿ ๐Ÿ ๐Ÿ \ No newline at end of file From 4b602ff335f43a8ae0b4f70238cd187ccea88995 Mon Sep 17 00:00:00 2001 From: sig Date: Mon, 5 Oct 2020 13:38:28 +0100 Subject: [PATCH 7/8] adds connectivity epic --- docs/installation/connectivity.md | 266 ++++++++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 docs/installation/connectivity.md diff --git a/docs/installation/connectivity.md b/docs/installation/connectivity.md new file mode 100644 index 000000000..04d9562a8 --- /dev/null +++ b/docs/installation/connectivity.md @@ -0,0 +1,266 @@ +--- +title: Connectivity +id: connectivity +--- + + +To connect to the outside world, your Bee node needs to be able to both send and receive messages from the outside world. Normally, your router will not allow other IP's on the internet to connect, unless you have connected to them first. In Swarm, we welcome newcomers, as long as they play by the rules. If a node misbehaves, we will simply add it to a list of blocked nodes and refuse future connections from them. + +In Swarm, every Bee counts! To make sure all Bees can join the swarm, below you will find a detailed guide to navigating your way through your network and making out into the wild so you can buzz with the crowd. If you still have problems, join us in [The Beehive](http://beehive.ethswarm.org/) and we'll help you find the way! ๐Ÿ ๐Ÿ ๐Ÿ ๐Ÿ ๐Ÿ + +### Networking Basics + +In a network, each computer is assigned an IP. Each IP is then subdivided into thousands of *sockets* or *ports*, each of which has an incoming and outgoing component. + +In a completely trusted network of computers, connections to or from any of these ports are allowed. However, to protect ourselves from nefarious actors when we join the wider internet, it is sometimes important to filter this traffic so that some of these ports are off limits to the public. + +In order to allow other Bee nodes we have previously not met to be able to send messages to our p2p port, usually `7070`, we must ensure that our network is set up to receive incoming connections. + +:::info +There are also some ports which you should never expose to the outside internet. Make sure that your `api-addr`, usually port `8080` is only exposed in `Gateway Mode` and your `--debug-api-addr`, usually `6060` is never exposed to the internet. It is good practice to employ one or more firewalls which block traffic on every port except for those for whom you are expecting it. +::: + +## Your IP + +When you connect to the internet, you are assigned a unique number called an IP Address. IP stands for **Internet Protocol**. The most prevalent IP version used is *still* the archaic [IPv4](https://en.wikipedia.org/wiki/IPv4) which was invented way back in 1981. IPv6 is available but not well used. Due to the mitigation of the deficiencies within this standard, we may encounter some complications. + + +### Datacenters and Computers Connected Directly to the Internet + +If you are renting space in a datacenter, the chances are that your computer will be connected directly to the real internet. This means that the IP of your networking interface will be directly set to be the same as your public IP. + +You can investigate this by running: + +```sh +ifconfig +``` + +or + +```sh +ip address +``` + +Your output should contain something like: + +``` +eth0: flags=4163 mtu 1500 + inet 178.128.196.191 netmask 255.255.240.0 broadcast 178.128.207.255 +``` + +Here we can see our computer's **public IP** `178.128.196.191`. This is the address that is used by other computers we connect to over the internet. We can very this using a third party service such as *icanhazip*. + +```sh +curl icanhazip.com +``` + +``` +178.128.196.191 +``` + +If these numbers correspond, congratulations! You may skip the next section! + +### Home, Commercial and Business Networks and Other Networks Behind NAT + +To address the [scarcity of IP numbers](https://en.wikipedia.org/wiki/IPv4_address_exhaustion), Network Address Translation (NAT) was implemented. This approach creates a smaller, private network which many devices connect to in order to share a public IP. Traffic destined for the internet at large is then mediated by another specialised computer. In the cases of the a home network, this computer is the familiar home router, normally also used to provide a wifi network. + +If we run the above commands to find the computer's IP in this scenario, we will see a different output. + +```sh +ip address +``` + +``` +en0: flags=8863 mtu 1500 + ... + inet 192.168.0.10 netmask 0xffffff00 broadcast 192.168.0.255 + ... +``` + +Here we can see that, instead of the public IP, we can see that our computers IP is `192.168.0.10`. This is part of the IP address space that the Internet Engineering Task Force has designated for [private networks](https://en.wikipedia.org/wiki/Private_network). + +As this IP won't work on the global internet, our router remembers that our computer has been assigned this IP. It then uses Network Address Translation to modify all requests from our computer to another computer somewhere in the internet. As the requests pass through the router it changes our local IP to the public IP of the router, and vice versa when the responses are sent back, from the public IP to the local one. + +#### Navigating Through the NAT + +The presence of Network Address Translations presents two problems for p2p networking. + +The first is that it can be difficult for programs running on our computer to know our real public IP as it is not explicitly known by our computer's networking interface, which is configured with a private network IP. This is a relatively easy problem to solve as we can simply discover our public IP and then specify it in Bee's configuration, or indeed determine it using other means. + +The second issue is that our router has only 65535 ports to expose to the public network, however, *each device on your private network* is capable of exposing 65535 *each*. To the global internet, it appears that there is only one set of ports to connect to, whereas, in actual fact, there is a full set of ports for each of the devices which are connected to the private network. To solve this second problem, routers commonly employ an approach known as *port forwarding*. + +Bee's solution to these problems come in two flavours, automatic and manual. + +##### Automatic: Universal Plug and Play (UPNP) + +UPNP is a protocol designed to simplify the administration of NAT and port forwarding by the end user by providing an API which software running within the network can use to ask the router for the external IP and to request for ports to be forwarded to the internal IP of the computer running the software. + +```danger +UPNP can be considered a security risk as it exposes your (real) public IP to any processes running on your computer, and also allows them to open arbitrary ports which may be used to transfer malicious traffic, for example a [RAT](https://en.wikipedia.org/wiki/Remote_desktop_software#RAT). We recommend you disable UPNP on your router and use manual port forwarding as described below. +``` + +Bee will use UPNP to determine your public IP, which is required for various internal processes. + +In addition to this, a request will be sent to your router to ask it to forward a random one of it's ports, which are exposed directly to the internet, to the Bee p2p port (usually `7070`) which your computer is exposing only to the private network. Doing this creates a tunnel through which other Bee's may connect to your computer safely. + +If you start your Bee node in a private network with UPNP available, the output of the addresses endpoint of your debug API will look something like this: + +```json +[ + "/ip4/127.0.0.1/tcp/7072/p2p/16Uiu2HAm5zcoBFWmqjDTwGy9RXepBFF8idy6Pr312obMwwxdJSUP", + "/ip4/192.168.0.10/tcp/7072/p2p/16Uiu2HAm5zcoBFWmqjDTwGy9RXepBFF8idy6Pr312obMwwxdJSUP", + "/ip6/::1/tcp/7072/p2p/16Uiu2HAm5zcoBFWmqjDTwGy9RXepBFF8idy6Pr312obMwwxdJSUP", + "/ip4/86.98.94.9/tcp/20529/p2p/16Uiu2HAm5zcoBFWmqjDTwGy9RXepBFF8idy6Pr312obMwwxdJSUP" +] +``` + +Note that the port in the external [multiaddress](https://docs.libp2p.io/concepts/addressing/) is the router's randomly selected `20529` which is forwarded by the router to `192.168.0.10:7070`. + +##### Manual: Configure Your Router and Bee + +Inspecting the underlay addresses in the output of the addresses endpoint our debug API, we can see addresses only for *localhost* `127.0.0.1` and our *private network IP* `192.168.0.10`. Bee must be having trouble navigating our NAT. + +```sh +[ + "/ip4/127.0.0.1/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB", + "/ip4/192.168.0.10/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB", + "/ip6/::1/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB", +] +``` + +To help fix the first problem, let's determine our public IP. + +```sh +curl icanhazip.com +``` + +``` +86.98.94.9 +``` + +Now we can simply supply this IP in our Bee configuration on startup. + +Solving our second problem is a little more difficult as we will need to interact with our router's firmware, which is a little cranky. + +Each router is different, but the concept is usually the same. Log in to your router by navigating your browser to your router's configuration user interface, usually at [http://192.168.0.1](http://192.168.0.1). You will need to log in with a password. Sadly, passwords are often left to be the defaults, which can be found readily on the internet. + +Once logged in, find the interface to set up port forwarding. The [Port Forward](https://portforward.com/router.htm) website provides some good information, or you may refer to your router manual or provider. + +Here, we will then set up a rule that forwards port `7070` of our internal IP `192.168.0.10` to the same port `7070` of our external IP. + +Now, when requests arrive at our external address `86.98.94.9:7070` they are modified by our router and forwarded to our internal IP and port `192.168.0.10:7070`. + +Sometimes this can be a little tricky, so let's verify we are able to make a TCP connection using [netcat](https://nmap.org/ncat/). + +First, with Bee **not** running, let's set up a simple TCP listener using Netcat on the same machine we would like to run Bee on. + +```sh +nc -l 0.0.0.0 7070 +``` + +```sh +nc -zv 86.98.94.9 7070 +``` + +``` +Connection to 86.98.94.9 port 7072 [tcp/*] succeeded! +``` +Success! โœจ + +If this didn't work for you, check out our [Debugging Connectivity]() guide below. + +If it did, let's start our Bee node with the `--nat-addr` configured. + +```sh +bee start --nat-addr 86.98.94.9:7070 +``` + +Checking our addresses endpoint again, we can now see that Bee has been able to successfully assign a public address! Congratulations, your Bee is now connected to the outside world! + +```sh +[ + "/ip4/127.0.0.1/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB", + "/ip4/192.168.0.10/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB", + "/ip6/::1/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB", + "/ip4/86.98.94.9/tcp/7070/p2p/16Uiu2HAm8Hs91MzWuXfUyKrYaj3h8K8gzvRqzSK5gP9TNCwypkJB" +] +``` + +:::info +If you are regularly connecting and disconnecting to a network, you may also want to use your router's firmware to configure the router to reserve and only assign the same local network IP from it's DHCP pool to your computer's MAC address. This will ensure that your Bee seamlessly connects when you rejoin the network! +::: + +### Debugging Connectivity + +The above guide navigates your NAT, but there are still a few hurdles to overcome. To make sure there is a clear path from your computer to the outside world, let's follow our Bee's journey from the inside out. + +Let's set up a Netcat listener on all interfaces on the computer we'd like to run Bee on as we have above. + +```sh +nc -l 0.0.0.0 7070 +``` + +Now, let's verify we're above to test this by checking the connection on our local machine. + +```sh +nc -zv 127.0.0.1 7070 +``` + +``` +nc -zv 127.0.0.1 7070 +Connection to 127.0.0.1 port 7070 [tcp/*] succeeded! +``` + +This should be a no brainer, the connection between localhost in not normally mediated. + +If there is a problem here, the problem is with some other software running on your operating system or your operating system itself. Try a different port, such as `7071` and turning off any unneccesary software. If this doesn't work, you may need to try a different operating system environment. Please get in touch and we'll try to help! + +If we were successful, let's move on to the next stage. + +Let's find out what our IP looks like to the internet. + +```sh +curl icanhazip.com +``` + +``` +86.98.94.9 +``` + +Now try to connect to your port using the global IP. + +```sh +nc -zv 86.98.94.9 7070 +``` + +If this is successful, our Bee node's path is clear! + +If not, we can try a few things to make sure there are no barriers stopping us from getting through. + +1. Check your computers firewall. + +Sometimes your computer is configured to prevent connections. If you are on a private network mediated by NAT, you can check if this is the problem by trying to connect from another device on your network using the local IP `nc -zv 192.168.0.10 7070`. + +Ubuntu uses [UFW](https://help.ubuntu.com/community/UFW), MacOS can be configured using the *Firewall* tab in the *Security & Privacy* section of *System Preferences*. Windows uses [Defender Firewall](https://support.microsoft.com/en-us/help/4028544/windows-10-turn-microsoft-defender-firewall-on-or-off). + +For each of these firewalls, set a special rule to allow UDP and TCP traffic to pass through on port `7070`. You may want to limit this traffic to the Bee application only. + +2. Check your ingress firewall. + +For a datacenter hired server, this configuration will often take place in somewhere in the web user interface. Refer to your server hosting provider's documentation to work out how to open ports to the open internet. Ensure that both TCP and UDP traffic are allowed. + +Similarly, if you are connecting from within a private network, you may find that the port is blocked by the router. Each router is different, so consult your router's firware documentation to make sure there are no firewalls in place blocking traffic on your Bee's designated p2p port. + +You may check this using Netcat by trying to connect using your computer's public IP, as above `nc -zv 86.98.94.9 7070`. + +3. Docker + +Docker adds another level of complexity. + +To debug docker connectivity issues, we may use netcat as above to check port connections are working as expected. Double check that you are exposing the right ports to your local network, either by using the command line flags or in your docker-compose.yaml. You should be able to successfully check the connection locally using eg. `nc -zv localhost 7070` then follow instructions above to make sure your local network has the correct ports exposed to the internet. + +3. Something else entirely? + +Networking is a complex topic, but it keeps us all together. If you still can't connect to your Bee, get in touch via [The Beehive](http://beehive.ethswarm.org/) and we'll do our best to get you connected. In the swarm, no Bee is left behind. + + From bcfc87ed782a4ec85b82b4973796a5bd52c2679a Mon Sep 17 00:00:00 2001 From: sig Date: Mon, 5 Oct 2020 14:19:49 +0100 Subject: [PATCH 8/8] adds community --- docs/community/community.md | 8 +++++--- sidebars.js | 6 +++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/community/community.md b/docs/community/community.md index 649ab543c..82e530094 100644 --- a/docs/community/community.md +++ b/docs/community/community.md @@ -3,8 +3,10 @@ title: Community id: community --- +Swarm is all about community. We want to make sure you have the best possible experience as you join and enjoy being a part of the our new internet. -The Bee client has a vibrant community of developers and users who are ready to answer any questions and help you join the Swarm. +Swarm has a vibrant community of wonderful individuals who are eager to answer any questions and graciously welcome you to our swarm. -- Orange Lounge -- Mattermost +Join us at our self-sovereign [Bee Hive](https://beehive.ethswarm.org/) for peace, love, unity, respect, community, assistance and lots of highly obscure chat about cryptography. + +Thanks for being here with us, making a difference, we appreciate you! ๐Ÿ \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index f56a00b9d..7e85850df 100644 --- a/sidebars.js +++ b/sidebars.js @@ -30,8 +30,8 @@ module.exports = { "Bee Developers": [ 'bee-developers/useful-dev-info' ], - // "Community": [ - // 'community/community' - // ] + "Community": [ + 'community/community' + ] }, }; \ No newline at end of file