Hyperledger Besu is an open-source Ethereum client designed for demanding enterprise applications requiring secure, high-performance transaction processing in a private network. It's developed under the Apache 2.0 license and written in Java.

1. Initial configuration

Create a service user for the execution service, create data directory and assign ownership.

sudo adduser --system --no-create-home --group execution
sudo mkdir -p /var/lib/besu
sudo chown -R execution:execution /var/lib/besu

Install dependencies.

sudo apt install -y openjdk-17-jdk libjemalloc-dev jq

2. Install Binaries

  • Downloading binaries is often faster and more convenient.

  • Building from source code can offer better compatibility and is more aligned with the spirit of FOSS (free open source software).

Option 1 - Download binaries

Run the following to automatically download the latest linux release, un-tar and cleanup.

TAG=$(curl -s $RELEASE_URL | jq -r .tag_name)

echo Downloading URL: $BINARIES_URL

cd $HOME
wget -O besu.tar.gz $BINARIES_URL
tar -xzvf besu.tar.gz -C $HOME
rm besu.tar.gz
sudo mv $HOME/besu-* besu

Install the binaries.

sudo mv $HOME/besu /usr/local/bin/besu
Option 2 - Build from source code

Build the binaries.

mkdir -p ~/git
cd ~/git
# Clone the repo
git clone
cd besu
# Get new tags
git fetch --tags
# Get latest tag name
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
# Checkout latest tag
git checkout $latestTag
# Build
./gradlew installDist

Verify Besu was properly built by checking the version.

./build/install/besu/bin/besu --version

Sample output of a compatible version.


Install the binaries.

sudo cp -a $HOME/git/besu/build/install/besu /usr/local/bin/besu

3. Setup and configure systemd

Create a systemd unit file to define your execution.service configuration.

sudo nano /etc/systemd/system/execution.service

Paste the following configuration into the file.

Description=Besu Execution Layer Client service for Mainnet

ExecStart=/usr/local/bin/besu/bin/besu \
  --network=mainnet \
  --p2p-port=30303 \
  --rpc-http-port=8545 \
  --engine-rpc-port=8551 \
  --max-peers=25 \
  --metrics-enabled=true \
  --metrics-port=6060 \
  --rpc-http-enabled=true \
  --sync-mode=SNAP \
  --data-storage-format=BONSAI \
  --Xbonsai-limit-trie-logs-enabled=true \
  --data-path="/var/lib/besu" \
  --Xplugin-rocksdb-high-spec-enabled \

Running less than 32GB of RAM? Deleting the flag, --Xplugin-rocksdb-high-spec-enabled is advisable.

To exit and save, press Ctrl + X, then Y, then Enter.

Run the following to enable auto-start at boot time.

sudo systemctl daemon-reload
sudo systemctl enable execution

Finally, start your execution layer client and check it's status.

sudo systemctl start execution
sudo systemctl status execution

Press Ctrl + C to exit the status.

4. Helpful execution client commands

sudo journalctl -fu execution | ccze

A properly functioning Besu execution client will indicate "Fork-Choice-Updates". For example,

2022-03-19 04:09:36.315+00:00 | vert.x-worker-thread-0 | INFO  | EngineForkchoiceUpdated | Consensus fork-choice-update: head: 0xcd2a_8b32..., finalized: 0xfa22_1142...
2022-03-19 04:09:48.328+00:00 | vert.x-worker-thread-0 | INFO  | EngineForkchoiceUpdated | Consensus fork-choice-update: head: 0xff1a_f12a..., finalized: 0xfa22_1142...

Now that your execution client is configured and started, proceed to the next step on setting up your consensus client.

If you're checking the logs and see any warnings or errors, please be patient as these will normally resolve once both your execution and consensus clients are fully synced to the Ethereum network.

Last updated