Intermediate

How to run a Node on Ethereum Network

This tutorial is designed to guide users through the process of setting up and running their own node on the Ethereum network. The tutorial covers the necessary prerequisites and provides information on the various approaches to running a node, including the selection of client implementations, the environment, and the parameters for client settings. It also covers the different options for running the software on your own hardware or in the cloud and provides instructions on how to install and set up the chosen clients. The tutorial also includes information on how to operate and monitor the node and provides troubleshooting tips for common issues that may arise.

PREREQUISITES

You should understand what an Ethereum node is and why you might want to run a client. This is covered in Nodes and clients.

If you’re new to the topic of running a node or looking for a less technical path, we recommend first checking out our user-friendly introduction on running an Ethereum node.

CHOOSING AN APPROACH

The first step in spinning up your node is choosing your approach. Based on requirements and various possibilities, you must select the client implementation (of both execution and consensus clients), the environment (hardware, system), and the parameters for client settings.

This page will guide you through these decisions and help you find the most suitable way to run your Ethereum instance.

To choose from client implementations, see all the available Mainnet-ready execution clients, consensus clients and learn about client diversity.

Decide whether to run the software on your own hardware or in the cloud, considering clients’ requirements.

After preparing the environment, install the chosen clients either with beginner-friendly interface or manually using a terminal with advanced options.

When the node is running and syncing, you are ready to use it, but make sure to keep an eye on its maintenance.

Environment and hardware

Local or cloud

Ethereum clients are able to run on consumer-grade computers and don’t require any special hardware, like mining machines for example. Therefore, you have various options for deploying the node based on your needs. To simplify, let’s think about running a node on both a local physical machine and a cloud server:

• Cloud

  • Providers offer high server uptime and static public IP addresses

  • Getting a dedicated or virtual server can be more comfortable than building your own

  • Trade off is trusting a third party – server provider

  • Because of the required storage size for a full node, the price of a rented server might get high

• Own hardware

  • More trustless and sovereign approach

  • One time investment

  • An option to buy preconfigured machines

  • You have to physically prepare, maintain, and potentially troubleshoot the machine and networking

Both options have different advantages summed up above. If you are looking for a cloud solution, in addition to many traditional cloud computing providers, there are also services focused on deploying nodes. For example:

• QuikNode

• Blockdaemon

• Alchemy

Check out also nodes as a service for more options on hosted nodes.

Hardware

However, a censorship-resistant, decentralized network should not rely on cloud providers. Instead, running your node on your own local hardware is healthier for the ecosystem. Estimations show a large share of nodes run on the cloud, which could become a single point of failure.

Ethereum clients can run on your computer, laptop, server, or even a single-board computer. While running clients on your personal computer is possible, having a dedicated machine just for your node can significantly enhance its performance and security while minimizing the impact on your primary computer.

Using your own hardware can be very easy. There are many simple options as well as advanced setups for more technical people. So let’s look into the requirements and means for running Ethereum clients on your machine.

Requirements

Hardware requirements differ by client but generally are not that high since the node just needs to stay synced. Don’t confuse it with mining, which requires much more computing power. Sync time and performance do improve with more powerful hardware however.

Before installing any client, please ensure your computer has enough resources to run it. You can find the minimum and recommended requirements below.

The bottleneck for your hardware is mostly disk space. Syncing the Ethereum blockchain is very input/output intensive and requires a lot of space. It is best to have a solid-state drive (SSD) with hundreds of GBs of free space to spare even after the synchronization.

The size of the database and speed of the initial synchronization depends on the chosen client, its configuration and sync strategy.

Also make sure your internet connection is not limited by a bandwidth cap. It’s recommended to use an unmetered connection since initial sync and data broadcasted to the network could exceed your limit.

Operating system

All clients support major operating systems – Linux, MacOS, Windows. This means you can run nodes on regular desktop or server machines with the operating system (OS) that suits you the best. Make sure your OS is up to date to avoid potential issues and security vulnerabilities.

Minimum requirements

• CPU with 2+ cores

• 8 GB RAM

• 700GB free disk space

• 10+ MBit/s bandwidth

Recommended specifications

• Fast CPU with 4+ cores

• 16 GB+ RAM

• Fast SSD with 1+TB

• 25+ MBit/s bandwidth

The sync mode and client you choose will affect space requirements, but we’ve estimated the disk space you’ll need for each client below.

• Note: Erigon does not offer snap sync, but Full Pruning is possible (~500GB)

For consensus clients, space requirement also depends on client implementation and enabled features (e.g. validator slasher) but generally count with another 200GB needed for beacon data. With a large number of validators, the bandwidth load grows as well. You can find details on consensus client requirements in this analysis.

Plug-and-play solutions

The easiest option for running a node with your own hardware is using plug-and-play boxes. Preconfigured machines from vendors offer the most straightforward experience: order, connect, run. Everything is preconfigured and runs automatically with an intuitive guide and dashboard for monitoring and controlling the software.

• DappNode

• Avado

Ethereum on a single-board computer

An easy and cheap way of running an Ethereum node is to use a single board computer, even with an ARM architecture like the Raspberry Pi. Ethereum on ARM provides easy-to-run images of multiple execution and consensus client for Raspberry Pi and other ARM boards.

Small, affordable and efficient devices like these are ideal for running a node at home but keep in mind their limited performance.

SPINNING UP THE NODE

The actual client setup can be done either with automated launchers or manually, setting up client software directly.

For less advanced users, the recommended approach is to use a launcher, software that guides you through the installation and automates the client setup process. However, if you have some experience of using a terminal, the steps for manual setup should be simple to follow.

Guided setup

Multiple user-friendly projects aim to improve the experience of setting up a client. These launchers provide automatic client installation and configuration, with some even offering a graphical interface for guided setup and monitoring of clients.

Below are a few projects which can help you install and control clients just with a few clicks:

• DappNode – DappNode doesn’t come only with a machine from a vendor. The software, the actual node launcher and control center with many features can be used on arbitrary hardware.

• eth-docker – Automatized setup using Docker focused on easy and secure staking, requires basic terminal and Docker knowledge, recommended for a bit more advanced users.

• Stereum – Launcher for installing clients on a remote server via SSH connection with a GUI setup guide, control center, and many other features.

• NiceNode – Launcher with a straightforward user experience to run a node on your computer. Just choose clients and start them with a few clicks. Still in development.

Manual clients setup

The other option is to download, verify, and configure the client software manually. Even if some clients offer a graphical interface, a manual setup still requires basic skills with the terminal but offers much more versatility.

As explained before, setting up your own Ethereum node will require running a pair of consensus and execution clients. Some clients might include a light client of the other kind and sync without any other software needed. However, full trustless verification requires both implementations.

Getting the client software

First, you need to obtain your preferred execution client and consensus client software.

You can simply download an executable application or installation package that suits your operating system and architecture. Always verify the signatures and checksums of downloaded packages. Some clients also offer repositories or Docker images for easier installation and updates. All of the clients are open source, so you can also build them from the source. This is a more advanced method, but in some cases, it might be required.

Instructions for installing each client are provided in the documentation linked in the client lists above.

Here are the release pages of clients where you can find their pre-built binaries or instructions on installation:

Execution clients

• Besu

• Erigon (Doesn’t provide a pre-built binary, has to be compiled)

• Geth

• Nethermind

It is also worth noting that client diversity is an issue on the execution layer. It is recommended that readers consider running a minority execution client.

Consensus clients

• Lighthouse

• Lodestar (Doesn’t provide a pre-built binary, only a Docker image or to be build from source)

• Nimbus

• Prysm

• Teku

Client diversity is critical for consensus nodes running validators. If majority of validators is running a single client implementation, network security is at risk. It is therefore recommended to consider choosing a minority client.

See the latest network client usage and learn more about client diversity.

Verifying the software

When downloading software from the internet, it’s recommended to verify its integrity. This step is optional but especially with crucial infrastracture piece like the Ethereum client, it’s important to be aware of potential attack vectors and avoid them. If you downloaded a pre-built binary, you need to trust it and risk that an attacker could swap the executable for a malicious one.

Developers sign released binaries with their PGP keys so you can cryptographically verify you are running exactly the software they created. You just need to obtain public keys used by developers, which can be found on client release pages or in documentation. After downloading the client release and its signature, you can use a PGP implementation, e.g. GnuPG to easily verify them. Check out a tutorial on veryifing open-source software using gpg on linux or Windows/MacOS.

Another form of verification is to make sure that the hash, a unique cryptographic fingerprint, of the software you downloaded matches the one provided by developers. This is even easier than using PGP, and some clients offer only this option. Just run the hash function on the downloaded software and compare it to the one from the release page. For example:

1sha256sum teku-22.6.1.tar.gz2
39b2f8c1f8d4dab0404ce70ea314ff4b3c77e9d27aff9d1e4c1933a5439767dde4

Client setup

After installing, downloading, or compiling the client software, you are ready to run it. This only means it has to be executed with the proper configuration. Clients offer rich configuration options, which can enable various features.

Let’s start with options that can significantly influence client performance and data usage. Sync modes represent different methods of downloading and validating blockchain data. Before starting the node, you should decide what network and sync mode to use. The most important things to consider are the disk space, and sync time the client will need. Pay attention to the client’s docs to determine which sync mode is the default. If that doesn’t suit you, pick another one based on the level of security, available data, and cost. Apart from the synchronization algorithm, you can also set pruning of different kinds of old data. Pruning enables deleting outdated data, e.g. removing state trie nodes that are unreachable from recent blocks.

Other basic configuration options are, e.g. choosing a network – Mainnet or testnets, enabling HTTP endpoint for RPC or WebSockets, etc. You can find all features and options in the client’s documentation. Various client configurations can be set by executing the client with the corresponding flags directly in the CLI or config file. Each client is a bit different; please always refer to its official documentation or help page for details on config options.

For testing purposes, you might prefer to run a client on one of the testnet networks. See overview of supported networks.

Examples of running execution clients with basic configuration can be found in next section.

Starting the execution client

Before starting the Ethereum client software, perform a last check that your environment is ready. For example, make sure:

• There is enough disk space considering the chosen network and sync mode.

• Memory and CPU are not halted by other programs.

• The operating system is updated to the latest version.

• The system has the correct time and date.

• Your router and firewall accept connections on listening ports. By default, Ethereum clients use a listener (TCP) port and a discovery (UDP) port, both on 30303 by default.

Run your client on a testnet first to help make sure everything is working correctly.

You need to declare any client settings that aren’t default at the start. You can use flags or the config file to declare your preferred configuration. Set of features and config syntax of each client differs. Check out your client’s documentation for the specifics.

Execution and consensus clients communicate via an authenticated endpoint specified in Engine API. In order to connect to a consensus client, the execution client must generate a jwtsecret at a known path. For security and stability reasons, clients should run on the same machine, and both clients must know this path as it is used to authenticate a local RPC connection between them. The execution client must also define a listening port for authenticated APIs.

This token is generated automatically by the client software, but in some cases, you might need to do it yourself. You can generate it using OpenSSL:

1openssl rand -hex 32 > jwtsecret2

Running an execution client

This section will guide you through starting execution clients. It only serves as an example of a basic configuration, which will start the client with these settings:

• Specifies network to connect to, mainnet in our examples

  • You can instead choose one of testnets for preliminary testing of your setup

• Defines data directory, where all the data including blockchain will be stored

  • Make sure to substitute the path with a real one, e.g. pointing to your external drive

• Enables interfaces for communicating with the client

  • Including JSON RPC and Engine API for communication with consensus client

• Defines path to jwtsecret for authenticated API

  • Make sure to substitute the example path with a real one that can be accessed by clients, e.g. /tmp/jwtsecret

Please keep in mind that this is just a basic example, all other settings will be set to default. Pay attention to the documentation of each client to learn about default values, settings, and features. For more features, for example for running validators, monitoring, etc., please refer to the documentation of the specific client.

Note that backslashes \ in examples are only for formatting purposes; config flags can be defined in a single line.

Running Besu

This example starts Besu on mainnet, stores blockchain data in default format at /data/ethereum, enables JSON RPC and Engine RPC for connecting consensus client. Engine API is authenticated with token jwtsecret and only calls from localhost are allowed.

1besu --network=mainnet \2    --data-path=/data/ethereum \3    --rpc-http-enabled=true \4    --engine-rpc-enabled=true \5    --engine-host-allowlist="*" \6    --engine-jwt-enabled=true \7    --engine-jwt-secret=/path/to/jwtsecret8

Besu also comes with a launcher option that will ask a series of questions and generate the config file. Run the interactive launcher using:

1besu --Xlauncher2

Besu’s documentation contains additional options and configuration details.

Running Erigon

This example starts Erigon on mainnet, stores blockchain data at /data/ethereum, enables JSON RPC, defines which namespaces are allowed, and enables authentication for connecting the consensus client which is defined by the jwtsecret path.

1erigon --chain mainnet \2    --datadir /data/ethereum  \3    --http --http.api=engine,eth,web3,net \4    --authrpc.jwtsecret=/path/to/jwtsecret5

Erigon by default performs a full sync with 8GB HDD which will result in more than 2TB of archive data. Make sure datadir is pointing to disk with enough free space or look into --prune flag which can trim different kinds of data. Check the Erigon’s --help to learn more.

Running Geth

This example starts Geth on mainnet, stores blockchain data at /data/ethereum, enables JSON RPC and defines which namespaces are allowed. It also enables authentication for connecting consensus client which requires path to jwtsecret and also option defining which connections are allowed, in our example only from localhost.

1geth --mainnet \2    --datadir "/data/ethereum" \3    --http --authrpc.addr localhost \4    --authrpc.vhosts="localhost" \5    --authrpc.port 85516    --authrpc.jwtsecret=/path/to/jwtsecret7

Check docs for all configuration options and learn more about running Geth with a consensus client.

Running Nethermind

Nethermind offers various installation options. The package comes with various binaries, including a Launcher with a guided setup, which will help you to create the configuration interactively. Alternatively, you find Runner which is the executable itself and you can just run it with config flags. JSON RPC is enabled by default.

1Nethermind.Runner --config mainnet \2    --datadir /data/ethereum \3    --JsonRpc.JwtSecretFile=/path/to/jwtsecret4

Nethermind docs offer a complete guide on running Nethermind with consensus client.

An execution client will initiate its core functions, chosen endpoints, and start looking for peers. After successfully discovering peers, the client starts synchronization. The execution client will await a connection from consensus client. Current blockchain data will be available once the client is successfully synced to the current state.

Starting the consensus client

The consensus client must be started with the right port configuration to establish a local RPC connection to the execution client. The consensus clients have to be run with the exposed execution client port as configuration argument.

The consensus client also needs the path to the execution client’s jwt-secret in order to authenticate the RPC connection between them. Similar to execution examples above, each consensus client has a configuration flag which takes the jwt token file path as an argument. This must be consistent with the jwtsecret path provided to the execution client.

If you plan to run a validator, make sure to add a configuration flag specifying the Ethereum address of the fee recipient. This is where ether rewards for your validator accumulate. Each consensus client has an option, e.g. --suggested-fee-recipient=0xabcd1, that takes an Ethereum address as an argument.

When starting a Beacon Node on a testnet, you can save significant syncing time by using a public endpoint for Checkpoint sync.

Running a consensus client

Running Lighthouse

Before running Lighthouse, learn more on how to install and configure it in Lighthouse Book.

1lighthouse beacon_node2    --network mainnet \3    --datadir /data/ethereum \4    --http \5    --execution-endpoint http://127.0.0.1:8551 \6    --execution-jwt /path/to/jwtsecret \7

Running Lodestar

Install Lodestar software by compiling it or downloading the Docker image. Learn more in docs and more comprehensive setup guide.

1lodestar beacon \2    --rootDir="/data/ethereum" \3    --network=mainnet \4    --eth1.enabled=true \5    --execution.urls="http://127.0.0.1:8551" \6    --jwt-secret="/path/to/jwtsecret"7

Running Nimbus

Nimbus comes with both consensus and execution clients. It can be run on various devices even with very modest computing power. After installing dependencies and Nimbus itself, you can run its consensus client:

1nimbus_beacon_node \2    --network=mainnet \3    --web3-url=http://127.0.0.1:8551 \4    --rest \5    --jwt-secret="/path/to/jwtsecret"6

Running Prysm

Prysm comes with script which allows easy automatic installation. Details can be found in the Prysm docs.

1./prysm.sh beacon-chain \2    --mainnet3    --datadir /data/ethereum  \4    --execution-endpoint=http://localhost:8551  \5    --jwt-secret=/path/to/jwtsecret6

Running Teku

1teku --network mainnet \2    --data-path "/data/ethereum" \3    --ee-endpoint http://localhost:8551 \4    --ee-jwt-secret-file "/path/to/jwtsecret" \5