Document need for port 9000 to be open (fix #730) (#731)

Co-authored-by: Age Manning <Age@AgeManning.com>

Edited by Paul H when cherry-picking from master to v0.3.0-staging

book/src/SUMMARY.md

@@ -26,6 +26,7 @@
 * [Advanced Usage](./advanced.md)
     * [Database Configuration](./advanced_database.md)
 	* [Local Testnets](./local-testnets.md)
+    * [Advanced Networking](./advanced_networking.md)
 * [Contributing](./contributing.md)
 	* [Development Environment](./setup.md)
 * [FAQs](./faq.md)

book/src/advanced_networking.md

@@ -0,0 +1,77 @@
+# Advanced Networking
+
+Lighthouse's networking stack has a number of configurable parameters that can
+be adjusted to handle a variety of network situations. This section outlines
+some of these configuration parameters and their consequences at the networking
+level and their general intended use.
+
+
+### Target Peers
+
+The beacon node has a `--target-peers` CLI parameter. This allows you to
+instruct the beacon node how many peers it should try to find and maintain.
+Lighthouse allows an additional 10% of this value for nodes to connect to us.
+Every 30 seconds, the excess peers are pruned. Lighthouse removes the
+worst-performing peers and maintains the best performing peers.
+
+It may be counter-intuitive, but having a very large peer count will likely
+have a degraded performance for a beacon node in normal operation and during
+sync.
+
+Having a large peer count means that your node must act as an honest RPC server
+to all your connected peers. If there are many that are syncing, they will
+often be requesting a large number of blocks from your node. This means you
+node must perform a lot of work reading and responding to these peers. If you
+node is over-loaded with peers and cannot respond in time, other Lighthouse
+peers will consider you non-performant and disfavour you from their peer
+stores. You node will also have to handle and manage the gossip and extra
+bandwidth that comes from having these extra peers. Having a non-responsive
+node (due to overloading of connected peers), degrades the network as a whole.
+
+It is often the belief that a higher peer counts will improve sync times.
+Beyond a handful of peers, this is not true. On all current tested networks,
+the bottleneck for syncing is not the network bandwidth of downloading blocks,
+rather it is the CPU load of processing the blocks themselves. Most of the
+time, the network is idle, waiting for blocks to be processed. Having a very
+large peer count will not speed up sync.
+
+For these reasons, we recommend users do not modify the `--target-peer` count
+drastically and use the (recommended) default.
+
+
+### NAT Traversal (Port Forwarding)
+
+Lighthouse, by default, used port 9000 for both TCP and UDP. Lighthouse will
+still function if it is behind a NAT without any port mappings. Although
+Lighthouse still functions, we recommend that some mechanism is used to ensure
+that your Lighthouse node is publicly accessible. This will typically improve
+your peer count, allow the scoring system to find the best/most favourable
+peers for your node and overall improve the eth2 network.
+
+Lighthouse currently supports UPnP. If UPnP is enabled on your router,
+Lighthouse will automatically establish the port mappings for you (the beacon
+node will inform you of established routes in this case). If UPnP is not
+enabled, we recommend you manually set up port mappings to both of Lighthouse's
+TCP and UDP ports (9000 by default).
+
+### ENR Configuration
+
+Lighthouse has a number of CLI parameters for constructing and modifying the
+local Ethereum Node Record (ENR). Examples are `--enr-address`,
+`--enr-udp-port`, `--enr-tcp-port` and `--disable-enr-auto-update`. These
+settings allow you construct your initial ENR. Their primary intention is for
+setting up boot-like nodes and having a contactable ENR on boot. On normal
+operation of a Lighthouse node, none of these flags need to be set. Setting
+these flags incorrectly can lead to your node being incorrectly added to the
+global DHT which will degrades the discovery process for all Eth2 peers.
+
+The ENR of a Lighthouse node is initially set to be non-contactable. The
+in-built discovery mechanism can determine if you node is publicly accessible,
+and if it is, it will update your ENR to the correct public IP and port address
+(meaning you do not need to set it manually). Lighthouse persists its ENR, so
+on reboot it will re-load the settings it had discovered previously.
+
+Modifying the ENR settings can degrade the discovery of your node making it
+harder for peers to find you or potentially making it harder for other peers to
+find each other. We recommend not touching these settings unless for a more
+advanced use case. 

book/src/become-a-validator-docker.md

@@ -83,6 +83,11 @@ This is one of the earlier logs outputted, so you may have to scroll up or perfo
 > the genesis of the network is known (approx 2 days before the network
 > launches).
 
+> Note: Docker exposes ports TCP 9000 and UDP 9000 by default. Although not
+> strictly required, we recommend setting up port forwards to expose these
+> ports publicly. For more information see the FAQ or the [Advanced Networking](advanced_networking.html)
+> section
+
 To find an estimate for how long your beacon node will take to finish syncing, look for logs that look like this:
 
 ```bash

book/src/become-a-validator-source.md

@@ -55,6 +55,12 @@ Start your beacon node with:
 > Current values are either `altona` or `medalla`. This is true for all the
 > following commands in this document.
 
+> Note: Lighthouse, by default, opens port 9000 over TCP and UDP. Although not
+> strictly required, we recommend setting up port forwards to expose these
+> ports publicly. For more information see the FAQ or the [Advanced Networking](advanced_networking.html)
+> section
+
+
 You can also pass an external http endpoint (e.g. Infura) for the Eth1 node using the `--eth1-endpoint` flag:
 
 ```bash

book/src/become-a-validator.md

@@ -26,7 +26,6 @@ Once you've completed **either one** of these steps, you can move onto the next
 
 > Take note when running Lighthouse. Use the --testnet parameter to specify the testnet you whish to participate in. Medalla is currently the default, so make sure to use --testnet altona to join the Altona testnet.
 
-
 ## 2. Submit your deposit to Goerli
 
 <div class="form-signin" id="uploadDiv">

book/src/faq.md

@@ -79,3 +79,48 @@ repeats until the queue is cleared.
 
 Once a validator has been activated, there's no more waiting! It's time to
 produce blocks and attestations!
+
+### 3. Do I need to set up any port mappings
+
+It is not strictly required to open any ports for Lighthouse to connect and
+participate in the network. Lighthouse should work out-of-the-box. However, if
+your node is not publicly accessible (you are behind a NAT or router that has
+not been configured to allow access to Lighthouse ports) you will only be able
+to reach peers who have a set up that is publicly accessible. 
+
+There are a number of undesired consequences of not making your Lighthouse node
+publicly accessible. 
+
+Firstly, it will make it more difficult for your node to find peers, as your
+node will not be added to the global DHT and other peers will not be able
+to initiate connections with you.
+Secondly, the peers in your peer store are more likely to end connections with
+you and be less performant as these peers will likely be overloaded with
+subscribing peers. The reason being, that peers that have correct port
+forwarding (publicly accessible) are in higher demand than regular peers as other nodes behind NAT's
+will also be looking for these peers.
+Finally, not making your node publicly accessible degrades the overall network, making it more difficult for other
+peers to join and degrades the overall connectivity of the global network. 
+
+For these reasons, we recommend that you make your node publicly accessible. 
+
+Lighthouse supports UPnP. If you are behind a NAT with a router that supports
+UPnP you can simply ensure UPnP is enabled (Lighthouse will inform you in its
+initial logs if a route has been established). You can also manually set up
+port mappings in your router to your local Lighthouse instance. By default,
+Lighthouse uses port 9000 for both TCP and UDP. Opening both these ports will
+make your Lighthouse node maximally contactable. 
+
+#### 4. I have a low peer count and it is not increasing
+
+If you cannot find *ANY* peers at all. It is likely that you have incorrect
+testnet configuration settings. Ensure that the network you wish to connect to
+is correct (the beacon node outputs the network it is connecting to in the
+initial boot-up log lines). On top of this, ensure that you are not using the
+same `datadir` as a previous network. I.e if you have been running the
+`medalla` testnet and are now trying to join a new testnet but using the same
+`datadir` (the `datadir` is also printed out in the beacon node's logs on
+boot-up). 
+
+If you find yourself with a low peer count and is not reaching the target you
+expect. Try setting up the correct port forwards as described in `3.` above.