diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index a13ced95a..1ecfa9213 100644 --- a/book/src/SUMMARY.md +++ b/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) diff --git a/book/src/advanced_networking.md b/book/src/advanced_networking.md new file mode 100644 index 000000000..e70decbfb --- /dev/null +++ b/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. diff --git a/book/src/become-a-validator-docker.md b/book/src/become-a-validator-docker.md index fd3331b8a..ce45996fd 100644 --- a/book/src/become-a-validator-docker.md +++ b/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 diff --git a/book/src/become-a-validator-source.md b/book/src/become-a-validator-source.md index 6dc661035..b1a8db045 100644 --- a/book/src/become-a-validator-source.md +++ b/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 diff --git a/book/src/become-a-validator.md b/book/src/become-a-validator.md index bab262343..a8f01c38b 100644 --- a/book/src/become-a-validator.md +++ b/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
diff --git a/book/src/faq.md b/book/src/faq.md index 3839d1ecd..4038ec7a8 100644 --- a/book/src/faq.md +++ b/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.