Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added doc for Teku bootnode-only mode #646

Merged
merged 5 commits into from
Apr 2, 2025
+434 −33
Merged

Added doc for Teku bootnode-only mode #646

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
554b24a
Added doc for Teku bootnode-only mode
lucassaldanha Mar 31, 2025
5e6ef66
lint
lucassaldanha Mar 31, 2025
a526458
Remove note about validator duty metrics not enabled by default
lucassaldanha Mar 31, 2025
ca5364b
Edit bootnode content.
bgravenorst Apr 1, 2025
9287ac6
Fix linter errors.
bgravenorst Apr 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions docs/how-to/run-a-bootnode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
description: Run Teku as a bootnode.
sidebar_position: 13
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Run Teku as a bootnode

## What is a bootnode?

Check warning on line 11 in docs/how-to/run-a-bootnode.md

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Microsoft.HeadingPunctuation] Don't use end punctuation in headings.

Raw Output:
{"message": "[Microsoft.HeadingPunctuation] Don't use end punctuation in headings.", "location": {"path": "docs/how-to/run-a-bootnode.md", "range": {"start": {"line": 11, "column": 21}}}, "severity": "WARNING"}

When a new node joins the Ethereum network, it must connect to other nodes in the same network. This
process is referred to as peering.

Ethereum uses the Discovery protocol to find new peers. The process starts with a small set of nodes, known
as bootnodes, that are hard coded into Ethereum clients. The Discovery protocol allows nodes to locate and
exchange information about active peers, enabling them to dynamically join the network without needing a
full list of known nodes.

You can specify additional bootnodes using the [`--p2p-discovery-bootnodes`](../reference/cli#p2p-discovery-bootnodes) option.

:::note
Any Teku instance running as a beacon node already participates in the Discovery protocol and can serve
as a bootnode.
:::

Most users don’t need to run a bootnode. This mode is primarily useful for client teams, infrastructure
providers, or others who want to contribute to the health and connectivity of the Ethereum network.
Running a bootnode helps new nodes discover peers more reliably, but doesn't provide direct benefits to the operator.

## Run Teku in bootnode-only mode

You can run Teku in bootnode-only mode when you don't want to operate a full beacon node.
When running in bootnode-only mode, Teku will only enable its Discovery service.

In this mode, Teku only runs its Discovery service and doesn't:

- Synchronize with the chain
- Validate or produce blocks
- Respond to Beacon API queries.

To run Teku in bootnode-only mode, start Teku with the [`bootnode`](../reference/cli/subcommands/bootnode.md) subcommand:

```bash
teku bootnode <extra_options>
```

Here is an example of common options used for a mainnet bootnode:

```bash
teku bootnode \
--network="mainnet" \
--p2p-port=9000 \
--p2p-advertised-ip=116.250.191.71 \
--p2p-private-key-file=/opt/data/node-key.txt
```

This example configures a bootnode for Ethereum mainnet. It sets:

- The network to `mainnet`
- The external communication port using [`--p2p-port`](../reference/cli#p2p-port)
- The public IP address using [`--p2p-advertised-ip`](../reference/cli#p2p-advertised-ip)
- A persistent private key file using [`--p2p-private-key-file`](../reference/cli#p2p-private-key-file)

Using a persistent private key ensures the bootnode has a stable Ethereum Node Record (ENR), which others
can use to connect reliably.
7 changes: 0 additions & 7 deletions docs/reference/cli/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,6 @@ import TabItem from '@theme/TabItem';

This reference describes the syntax of the Teku command line interface (CLI) options.

:::caution

The CLI options are currently under development and may change.

:::

## Specify options

You can specify Teku options:
Expand Down Expand Up @@ -1469,7 +1463,6 @@ A comma-separated list of categories for which to track metrics.
Options are `JVM`, `PROCESS`, `BEACON`, `DISCOVERY`, `EVENTBUS`, `EXECUTOR`, `LIBP2P`, `NETWORK`,
`STORAGE`, `STORAGE_HOT_DB`, `STORAGE_FINALIZED_DB`, `REMOTE_VALIDATOR`, `VALIDATOR`,
`VALIDATOR_PERFORMANCE`, and `VALIDATOR_DUTY`.
All but `VALIDATOR_DUTY` categories are enabled by default.

When `metrics-categories` is used, only the categories specified in this option are enabled (all
other categories are disabled).
Expand Down
Loading
Loading