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

```toml
# 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

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

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

### Consensus Configuration

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

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

### Logging Configuration

```toml
# 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

```toml
# 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

```toml
# 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

```toml
# 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

```toml
# 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

```toml
# 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)
```toml
rpc-http-api=["ETH","NET","WEB3"]
```

#### Standard (Application RPC)
```toml
rpc-http-api=["ETH","NET","WEB3","TXPOOL","QBFT"]
```

#### Full Admin (Core RPC)
```toml
rpc-http-api=["ETH","NET","WEB3","TXPOOL","QBFT","ADMIN","DEBUG","TRACE"]
```

---

## Security Configuration

### CORS Configuration

```toml
# 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
```toml
permissions-nodes-config-file-enabled=true
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"
```

#### Account Permissioning (Validators)
```toml
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:

```bash
# 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