proxmox/docs/04-configuration/BESU_CONFIGURATION_GUIDE.md

Besu Configuration Guide

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Date: 2026-01-17
Version: Besu v23.10.0+
Purpose: Comprehensive configuration reference for Besu nodes

---

Overview

This guide provides complete configuration reference for Hyperledger Besu v23.10.0+. It covers valid configuration options, node type-specific patterns, and best practices.

---

Valid Configuration Options (Besu v23.10.0+)

Deprecated Options (Removed)

The following options are deprecated and should not be used:

Option	Status	Replacement
log-destination	❌ Deprecated	Use logging option
fast-sync-min-peers	❌ Incompatible with FULL	Remove when using sync-mode="FULL"
database-path	❌ Deprecated	Use data-path instead
trie-logs-enabled	❌ Deprecated	Removed - no replacement
accounts-enabled	❌ Deprecated	Removed - no replacement
max-remote-initiated-connections	❌ Deprecated	Removed - no replacement
rpc-http-host-allowlist	❌ Deprecated	Use firewall rules + CORS
rpc-tx-feecap="0x0"	❌ Invalid	Remove or use valid Wei value
tx-pool-max-size	❌ Legacy	Incompatible with layered implementation
tx-pool-price-bump	❌ Legacy	Incompatible with layered implementation
tx-pool-retention-hours	❌ Legacy	Incompatible with layered implementation

---

Core Configuration Options

Network Configuration

# Network identifier
network-id=138

# P2P network binding
p2p-host="0.0.0.0"
p2p-port=30303

# Maximum peer connections
max-peers=25

# Enable/disable peer discovery
discovery-enabled=true

Data Storage

# Root data directory (contains database, node keys)
data-path="/data/besu"

# Genesis block configuration
genesis-file="/genesis/genesis.json"

Consensus Configuration

# Consensus protocol (detected from genesis.json for QBFT/IBFT)
miner-enabled=false

# Sync mode (FULL, FAST, or SNAP)
sync-mode="FULL"

Logging Configuration

# Logging level: OFF, FATAL, WARN, INFO, DEBUG, TRACE, ALL
logging="WARN"  # Use WARN for validators/RPC, INFO for archive nodes

Logging Strategy:

• Validators: WARN (minimal logs, consensus critical)
• RPC Nodes: WARN (minimal logs, performance)
• Sentry/Archive: INFO (detailed logs for archival)

---

Node Type Configurations

Validator Node Configuration

Purpose: Participate in QBFT consensus, block production

# Besu Configuration for Validator Nodes
data-path="/data"
genesis-file="/config/genesis.json"

network-id=138
p2p-host="0.0.0.0"
p2p-port=30303

# Consensus
miner-enabled=false
sync-mode="FULL"

# RPC Configuration (DISABLED for security)
rpc-http-enabled=false
rpc-ws-enabled=false

# Logging (minimal)
logging="WARN"

# Permissioning
permissions-nodes-config-file-enabled=true
permissions-nodes-config-file="/config/permissions-nodes.toml"
permissions-accounts-config-file-enabled=true
permissions-accounts-config-file="/config/permissions-accounts.toml"

# Network
static-nodes-file="/config/static-nodes.json"
discovery-enabled=true

# P2P
max-peers=25

# Metrics
metrics-enabled=true
metrics-port=9545
metrics-host="0.0.0.0"

Key Features:

• ✅ RPC disabled (security)
• ✅ Minimal logging (WARN)
• ✅ Full sync mode
• ✅ Node and account permissioning enabled

---

RPC Node Configuration

Purpose: Serve JSON-RPC API requests (dApps, indexers, tools)

Core RPC Node

# Besu Configuration for Core/Admin RPC Nodes
data-path="/data/besu"
genesis-file="/genesis/genesis.json"

network-id=138
p2p-host="0.0.0.0"
p2p-port=30303

miner-enabled=false
sync-mode="FULL"

# RPC Configuration (full admin APIs)
rpc-http-enabled=true
rpc-http-host="0.0.0.0"
rpc-http-port=8545
rpc-http-api=["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN","DEBUG","TRACE"]
# CORS: Internal network only
rpc-http-cors-origins=["http://192.168.11.0/24","http://localhost","http://127.0.0.1"]

rpc-ws-enabled=true
rpc-ws-host="0.0.0.0"
rpc-ws-port=8546
rpc-ws-api=["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN"]
rpc-ws-origins=["*"]

# Logging (minimal)
logging="WARN"

# Permissioning
permissions-nodes-config-file-enabled=true
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

# Network
static-nodes-file="/var/lib/besu/static-nodes.json"
discovery-enabled=false  # Core RPC: internal only

# P2P
max-peers=25

# Metrics
metrics-enabled=true
metrics-port=9545
metrics-host="0.0.0.0"

Public RPC Node

# Minimal read-only APIs for public access
rpc-http-api=["ETH","NET","WEB3"]
rpc-http-cors-origins=["*"]
rpc-ws-enabled=false
discovery-enabled=true

ThirdWeb RPC Node

# ThirdWeb-compatible APIs
rpc-http-api=["ETH","NET","WEB3","DEBUG","TRACE"]
rpc-http-cors-origins=["*"]
rpc-ws-enabled=true
max-peers=50  # Higher peer count for connectivity
rpc-http-timeout=60

Key Features:

• ✅ RPC enabled with appropriate APIs
• ✅ Minimal logging (WARN)
• ✅ CORS configured appropriately
• ✅ Permissioning enabled

---

Sentry Node Configuration

Purpose: Full archive nodes, P2P relay between validators and external peers

# Besu Configuration for Sentry Nodes
data-path="/data/besu"
genesis-file="/genesis/genesis.json"

network-id=138
p2p-host="0.0.0.0"
p2p-port=30303

miner-enabled=false
sync-mode="FULL"  # Full archive mode

# RPC Configuration (internal only)
rpc-http-enabled=true
rpc-http-host="0.0.0.0"
rpc-http-port=8545
rpc-http-api=["ETH","NET","WEB3","ADMIN"]
rpc-http-cors-origins=["*"]

rpc-ws-enabled=true
rpc-ws-host="0.0.0.0"
rpc-ws-port=8546
rpc-ws-api=["ETH","NET","WEB3"]

# Logging (archive - detailed logs)
logging="INFO"

# Permissioning
permissions-nodes-config-file-enabled=true
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

# Network
static-nodes-file="/var/lib/besu/static-nodes.json"
discovery-enabled=true  # Open P2P discovery

# P2P
max-peers=25

# Metrics
metrics-enabled=true
metrics-port=9545
metrics-host="0.0.0.0"

Key Features:

• ✅ Full archive mode (sync-mode="FULL")
• ✅ Detailed logging (INFO)
• ✅ Open P2P discovery
• ✅ Internal RPC access

---

Configuration Patterns

Logging Levels by Use Case

Node Type	Logging Level	Rationale
Validator	WARN	Minimal logs, reduce I/O, focus on errors
RPC	WARN	Minimal logs, reduce I/O, better performance
Sentry/Archive	INFO	Detailed logs for archival and debugging

Sync Modes

Sync Mode	Description	Use Case
FULL	Full blockchain sync, all history	Validators, Archive nodes
FAST	Fast sync, recent history only	Non-archive RPC nodes
SNAP	Snapshot sync (if available)	Quick bootstrap

Note: fast-sync-min-peers option is incompatible with FULL sync mode.

RPC API Selection

Minimal (Public RPC)

rpc-http-api=["ETH","NET","WEB3"]

Standard (Application RPC)

rpc-http-api=["ETH","NET","WEB3","TXPOOL","QBFT"]

Full Admin (Core RPC)

rpc-http-api=["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN","DEBUG","TRACE"]

---

Security Configuration

CORS Configuration

# Internal network only (Core RPC)
rpc-http-cors-origins=["http://192.168.11.0/24","http://localhost","http://127.0.0.1"]

# Public access (Public RPC)
rpc-http-cors-origins=["*"]

Best Practice: Use firewall rules in combination with CORS for defense in depth.

Permissioning

Node Permissioning

permissions-nodes-config-file-enabled=true
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

Account Permissioning (Validators)

permissions-accounts-config-file-enabled=true
permissions-accounts-config-file="/config/permissions-accounts.toml"

---

Common Configuration Issues

Issue: Unknown Options Error

Symptom: Unknown options in TOML configuration file

Cause: Using deprecated options from older Besu versions

Solution: Remove deprecated options (see list above)

Issue: Invalid rpc-tx-feecap Value

Symptom: Configuration parsing error

Cause: rpc-tx-feecap="0x0" cannot be converted to Wei

Solution: Remove the option or use valid Wei value

Issue: fast-sync-min-peers with FULL sync

Symptom: Configuration warning or error

Cause: fast-sync-min-peers is incompatible with sync-mode="FULL"

Solution: Remove fast-sync-min-peers when using FULL sync mode

---

Configuration Validation

Use the validation script to check configurations:

# Validate all configs
./scripts/validate-besu-config.sh

# Validate specific config
./scripts/validate-besu-config.sh <config-file>

Validation checks:

• ✅ TOML syntax
• ✅ Deprecated options (should be 0)
• ✅ Required options present
• ✅ Valid option values (log levels, sync modes)
• ✅ Path references reasonable

---

Configuration File Locations

Source Project

• smom-dbis-138/config/ - Source configuration files
• smom-dbis-138-proxmox/templates/besu-configs/ - Template files

Deployment

• Validators: /etc/besu/config-validator.toml
• Sentries: /etc/besu/config-sentry.toml
• RPC Nodes: /etc/besu/config-rpc-*.toml

See docs/04-configuration/BESU_PATH_REFERENCE.md for complete path mapping.

---

Best Practices

1. Minimal Logging

• Use WARN for validators and RPC nodes
• Use INFO only for archive nodes that need detailed logs

2. Security

• Disable RPC on validators
• Use specific CORS origins (not wildcards) where possible
• Implement firewall rules for access control

3. Performance

• Use appropriate max-peers for network size
• Configure sync mode based on archival needs
• Remove deprecated options that may cause issues

4. Maintenance

• Validate configs before deployment
• Keep configs in version control
• Document any deviations from templates

---

Related Documentation

• docs/04-configuration/BESU_PATH_REFERENCE.md - Path structure reference
• docs/05-network/BESU_FIREWALL_RULES.md - Firewall configuration
• docs/04-configuration/BESU_CLEANUP_COMPLETE.md - Cleanup summary
• scripts/validate-besu-config.sh - Configuration validation

---

References

• Besu Official Documentation: https://besu.hyperledger.org/en/stable/
• Besu v23.10.0 Release Notes: Check for latest changes
• Configuration Options Reference: https://besu.hyperledger.org/en/stable/Reference/CLI/CLI-Syntax/

---

Last Updated: 2026-01-17
Version: Besu v23.10.0+
Status: Production Ready