Run an Ethereum mainnet full node on Ubuntu with Geth as the execution client and Lighthouse as the consensus client, both under systemd. It is for node operators and web3 developers who want their own RPC endpoint.
Prerequisites#
Since the merge, a full node needs two programs. Geth executes transactions and holds state. Lighthouse follows the beacon chain and tells Geth which block is the chain head. The two clients talk over the authenticated engine API on port 8551.
Hardware#
These figures come from the ethereum.org run a node page (opens in a new tab). Its recommended tier follows EIP-7870.
| Minimum | Recommended | |
|---|---|---|
| CPU | 2+ cores | 4+ fast cores |
| RAM | 16 GB | 32 GB |
| Disk | 2 TB NVMe SSD | 4 TB NVMe SSD |
| Bandwidth | 25 Mbit/s | 50 Mbit/s down, 15 Mbit/s up |
Plan for 32 GB of RAM. The Lighthouse book warns that 16 GB will likely cause out-of-memory errors during load spikes. The same ethereum.org page expects a node to outgrow 2 TB by 2027, so buy 4 TB if you can. It also advises against DRAM-less and QLC drives.
OS and tools#
- Ubuntu 24.04 LTS, or another Linux with glibc 2.34 or later. Starting with v8.3.0, the pre-built Lighthouse binaries need that glibc version. The release notes list Ubuntu 22.04+, Debian 12+ and RHEL 9+ as supported.
- A user account with
sudoaccess. - An accurate system clock. Geth rejects engine API tokens issued more than 60 seconds in the past or future.
Check glibc and the clock:
ldd --version
timedatectl statustimedatectl should report System clock synchronized: yes.
Install the tools this guide uses:
sudo apt update
sudo apt install -y curl gnupg openssl ufw1. Install Geth#
This guide uses Geth v1.17.9, the release marked latest on the go-ethereum releases page (opens in a new tab). Before you start, check that page and geth.ethereum.org/downloads (opens in a new tab) for a newer release.
Download the archive and its PGP signature:
mkdir -p ~/eth-downloads && cd ~/eth-downloads
GETH_VERSION=1.17.9-9dffe6e9
curl -LO https://gethstore.blob.core.windows.net/builds/geth-linux-amd64-${GETH_VERSION}.tar.gz
curl -LO https://gethstore.blob.core.windows.net/builds/geth-linux-amd64-${GETH_VERSION}.tar.gz.ascThe suffix 9dffe6e9 is the release commit. A newer release has a different suffix, so copy it from the downloads page. On ARM servers, replace amd64 with arm64.
Import the Go Ethereum Linux Builder key and verify the archive:
gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys FDE5A1A044FA13D2F7ADA019A61A13569BA28146
gpg --verify geth-linux-amd64-${GETH_VERSION}.tar.gz.asc geth-linux-amd64-${GETH_VERSION}.tar.gzThe output should say Good signature, and the fingerprint must match the one on the downloads page. A warning that the key is not certified is normal. If you see BAD signature, delete the file and stop.
Install the binary:
tar -xzf geth-linux-amd64-${GETH_VERSION}.tar.gz
sudo install -m 0755 geth-linux-amd64-${GETH_VERSION}/geth /usr/local/bin/geth
geth version2. Install Lighthouse#
This guide uses Lighthouse v8.3.1 from the Lighthouse releases page (opens in a new tab). It is a high-priority release that updates the trusted certificates after the eMudhra CA compromise. That matters here because checkpoint sync uses HTTPS.
cd ~/eth-downloads
LH_VERSION=v8.3.1
curl -LO https://github.com/sigp/lighthouse/releases/download/${LH_VERSION}/lighthouse-${LH_VERSION}-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/sigp/lighthouse/releases/download/${LH_VERSION}/lighthouse-${LH_VERSION}-x86_64-unknown-linux-gnu.tar.gz.ascOn ARM servers, use the aarch64-unknown-linux-gnu archive instead.
Verify the archive with the Sigma Prime key listed in the release notes:
gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 15E66D941F697E28F49381F426416DC3F30674B0
gpg --verify lighthouse-${LH_VERSION}-x86_64-unknown-linux-gnu.tar.gz.asc lighthouse-${LH_VERSION}-x86_64-unknown-linux-gnu.tar.gzInstall the binary:
tar -xzf lighthouse-${LH_VERSION}-x86_64-unknown-linux-gnu.tar.gz
sudo install -m 0755 lighthouse /usr/local/bin/lighthouse
lighthouse --version3. Create a service user, data directories and the JWT secret#
Both clients run as an unprivileged ethereum user. The JWT secret is a file of 32 bytes in hex that both clients read. Lighthouse signs engine API requests with it, and Geth checks them with it.
sudo useradd --system --no-create-home --shell /usr/sbin/nologin ethereum
sudo mkdir -p /var/lib/ethereum/geth /var/lib/ethereum/lighthouse
openssl rand -hex 32 | tr -d "\n" | sudo tee /var/lib/ethereum/jwt.hex > /dev/null
sudo chown -R ethereum:ethereum /var/lib/ethereum
sudo chmod 600 /var/lib/ethereum/jwt.hexCreate the file before Geth starts. If the file is missing, Geth writes a new secret to that path. If the file holds anything other than 32 bytes of hex, Geth refuses to start.
4. Create the systemd units#
Geth#
Create /etc/systemd/system/geth.service:
1[Unit]
2Description=Geth execution client (mainnet)
3Wants=network-online.target
4After=network-online.target
5
6[Service]
7Type=simple
8User=ethereum
9Group=ethereum
10ExecStart=/usr/local/bin/geth \
11 --mainnet \
12 --datadir /var/lib/ethereum/geth \
13 --authrpc.addr 127.0.0.1 \
14 --authrpc.port 8551 \
15 --authrpc.vhosts localhost \
16 --authrpc.jwtsecret /var/lib/ethereum/jwt.hex \
17 --http \
18 --http.addr 127.0.0.1 \
19 --http.port 8545 \
20 --http.api eth,net,web3 \
21 --history.chain postmerge
22Restart=on-failure
23RestartSec=5
24TimeoutStopSec=300
25LimitNOFILE=65536
26
27[Install]
28WantedBy=multi-user.targetWhat these settings do:
- The
--authrpc.*flags serve the engine API on127.0.0.1:8551and require the JWT secret. --httpwith--http.addr 127.0.0.1serves JSON-RPC on port 8545 to this machine only.--history.chain postmergeskips pre-merge block bodies and receipts. The Ethereum Foundation estimates this saves 300 to 500 GB. The default isall. Use it if you need to serve pre-merge blocks or receipts over RPC.TimeoutStopSec=300gives Geth time to shut down cleanly and write its caches to disk before systemd kills it.
Geth uses snap sync by default, so the unit has no --syncmode flag.
Lighthouse#
Create /etc/systemd/system/lighthouse.service:
1[Unit]
2Description=Lighthouse beacon node (mainnet)
3Wants=network-online.target geth.service
4After=network-online.target geth.service
5
6[Service]
7Type=simple
8User=ethereum
9Group=ethereum
10ExecStart=/usr/local/bin/lighthouse bn \
11 --network mainnet \
12 --datadir /var/lib/ethereum/lighthouse \
13 --execution-endpoint http://localhost:8551 \
14 --execution-jwt /var/lib/ethereum/jwt.hex \
15 --checkpoint-sync-url https://mainnet.checkpoint.sigp.io \
16 --http \
17 --http-address 127.0.0.1 \
18 --http-port 5052
19Restart=on-failure
20RestartSec=5
21TimeoutStopSec=300
22LimitNOFILE=65536
23
24[Install]
25WantedBy=multi-user.targetWhat the flags do:
--network mainnetnames the network explicitly, as the Lighthouse book advises.--execution-endpointand--execution-jwtpoint at Geth's engine API and the shared secret.--checkpoint-sync-urlmakes Lighthouse start from a recent finalized state instead of genesis. The URL is Sigma Prime's public mainnet server. You can pick any provider from the checkpoint sync endpoint list (opens in a new tab).--httpserves the beacon API on127.0.0.1:5052. The status checks below use it. The Lighthouse book warns that exposing it to the internet opens the node to denial-of-service attacks.
Checkpoint sync only runs on an empty beacon database. To redo it later, stop the service and delete the beacon directory:
sudo systemctl stop lighthouse
sudo rm -rf /var/lib/ethereum/lighthouse/beacon
sudo systemctl start lighthouse5. Open the P2P ports#
Only the peer-to-peer ports should be reachable from the internet:
| Port | Protocol | Client | Open to internet |
|---|---|---|---|
| 30303 | TCP and UDP | Geth P2P and discovery | Yes |
| 9000 | TCP and UDP | Lighthouse P2P and discovery | Yes |
| 9001 | UDP | Lighthouse QUIC | Yes |
| 8551 | TCP | Engine API | No |
| 8545 | TCP | Geth JSON-RPC | No |
| 5052 | TCP | Lighthouse beacon API | No |
Allow SSH first so you don't lock yourself out, then add the P2P rules:
sudo ufw allow OpenSSH
sudo ufw allow 30303/tcp
sudo ufw allow 30303/udp
sudo ufw allow 9000/tcp
sudo ufw allow 9000/udp
sudo ufw allow 9001/udp
sudo ufw enableIf the server is behind a NAT router, forward the same ports on the router.
6. Start both clients#
sudo systemctl daemon-reload
sudo systemctl enable --now geth lighthouseFollow the logs in two terminals:
journalctl -fu gethjournalctl -fu lighthouseGeth should log Loaded JWT secret file followed by your path. Lighthouse should log Starting checkpoint sync, then Loaded checkpoint block and state. Once Lighthouse has a head, Geth starts snap sync, which can take many hours. The Geth docs note that HDDs and cheaper SSDs can struggle to sync.
Verify the checkpoint#
The Lighthouse book says to cross-check the slot and block root of the loaded checkpoint against a second trusted source. Copy block_slot and block_root from the Loaded checkpoint block and state log line. Then ask a different provider from the endpoint list for the root at that slot:
curl -s https://beaconstate.ethstaker.cc/eth/v1/beacon/blocks/<block_slot>/rootReplace <block_slot> with the number from your log. The returned root must match block_root, ignoring the 0x prefix. If the provider returns an error, compare with a block explorer instead.
Verify it works#
Check the execution client with eth_syncing:
curl -s -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
http://127.0.0.1:8545While Geth syncs, the result is an object with currentBlock, highestBlock and snap sync counters. Once Geth is synced, the result is false. Geth also returns false before sync starts, so false on its own does not prove the node is synced. Check the block number and peer count as well:
curl -s -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
http://127.0.0.1:8545
curl -s -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' \
http://127.0.0.1:8545A block number of 0x0 means Geth is still waiting for a head from Lighthouse.
Check the consensus client with the standard beacon API:
curl -s http://127.0.0.1:5052/eth/v1/node/syncing
curl -s http://127.0.0.1:5052/eth/v1/node/peer_count
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5052/eth/v1/node/healthA healthy node shows "is_syncing":false, "sync_distance":"0", "is_optimistic":false and "el_offline":false. The health endpoint returns 200 when the node is ready. It returns 206 while the node is syncing, is optimistic, or has lost contact with Geth. Once both clients are synced, Lighthouse logs Synced lines that show blocks as (verified).
Troubleshooting#
Geth warns "Post-merge network, but no beacon client seen"#
Geth can't sync without a consensus client. Check that Lighthouse is running and that its --execution-endpoint is http://localhost:8551:
systemctl status lighthouseLighthouse logs "Failed jwt authorization"#
Either the two clients are reading different secrets, or the clocks disagree. Check that both units use /var/lib/ethereum/jwt.hex. If Geth logged Generated JWT secret, the file was missing when Geth started and Geth wrote a new one. Restart Lighthouse so it reads the same file. Then confirm that timedatectl shows a synchronized clock.
Geth exits with "history pruning required"#
This happens when you point the unit at an older datadir that still holds pre-merge history. With --history.chain postmerge set, Geth refuses to start until you prune the database. Stop Geth and prune the database as the ethereum user:
sudo systemctl stop geth
sudo -u ethereum geth prune-history --datadir /var/lib/ethereum/geth --history.chain postmerge
sudo systemctl start gethIn Geth v1.17.9, prune-history requires the --history.chain flag. The Geth history pruning docs (opens in a new tab) warn that pruning while Geth is running can corrupt data.
Lighthouse fails with a GLIBC version error#
Pre-built Lighthouse binaries from v8.3.0 on need glibc 2.34 or later. Upgrade the OS, or build from source as the Lighthouse book (opens in a new tab) describes.
Next steps#
- Watch both release pages for the next fork. Its execution side is called Amsterdam and its consensus side Gloas. Geth v1.17.9 and Lighthouse v8.3.x activate it on the Hoodi testnet on 26 October 2026. The Lighthouse v8.3.0 notes say Gloas is not yet scheduled on mainnet and that mainnet will need v9.0.0. Upgrade both clients before any mainnet fork date.
- Add monitoring. Geth's
--metricsflag serves Prometheus data at127.0.0.1:6060/debug/metrics/prometheus. Lighthouse's--metricsflag serves it on127.0.0.1:5054. Keep both ports private. If you have not set up Prometheus and Grafana before, Monitor a CometBFT node with Prometheus and Grafana walks through the stack. - If you plan to validate, add the Lighthouse validator client. Generate validator keys on an offline machine. Never paste a mnemonic into a website or a shared terminal.