proxmox/docs/06-besu/BESU_ALLOWLIST_QUICK_START.md

Besu Allowlist Quick Start Guide

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

---

Complete runbook: See docs/BESU_ALLOWLIST_RUNBOOK.md for detailed explanations.

---

Quick Execution Order

1. Extract Enodes from All Nodes

Option A: If RPC is enabled (recommended for RPC nodes):

# For each node, extract enode via RPC
export RPC_URL="http://192.168.11.13:8545"
export NODE_IP="192.168.11.13"
bash scripts/besu-extract-enode-rpc.sh > enode-192.168.11.13.txt

Option B: If RPC is disabled (for validators):

# SSH to node or run locally on each node
export DATA_PATH="/data/besu"
export NODE_IP="192.168.11.13"
bash scripts/besu-extract-enode-nodekey.sh > enode-192.168.11.13.txt

2. Collect All Enodes (Automated)

Update the NODES array in scripts/besu-collect-all-enodes.sh with your node IPs, then:

bash scripts/besu-collect-all-enodes.sh

This creates a working directory (e.g., besu-enodes-20241219-140600/) with:

• collected-enodes.txt - All valid enodes
• duplicates.txt - Duplicate entries (if any)
• invalid-enodes.txt - Invalid entries (if any)

3. Generate Allowlist Files

# From the working directory created in step 2
bash scripts/besu-generate-allowlist.sh besu-enodes-*/collected-enodes.txt 192.168.11.13 192.168.11.14 192.168.11.15 192.168.11.16 192.168.11.18

This generates:

• static-nodes.json - Validators only (for QBFT)
• permissions-nodes.toml - All nodes (validators + sentries + RPC)

4. Validate Generated Files

bash scripts/besu-validate-allowlist.sh static-nodes.json permissions-nodes.toml

Must show: ✓ All enodes validated successfully

5. Deploy to All Containers

bash scripts/besu-deploy-allowlist.sh static-nodes.json permissions-nodes.toml

6. Restart Besu Services

On Proxmox host (192.168.11.10):

for vmid in 106 107 108 109 110 111 112 113 114 115 116 117; do
    echo "Restarting container $vmid..."
    pct exec $vmid -- systemctl restart besu-validator 2>/dev/null || \
    pct exec $vmid -- systemctl restart besu-sentry 2>/dev/null || \
    pct exec $vmid -- systemctl restart besu-rpc 2>/dev/null || true
done

7. Verify Peer Connections

# Check all nodes
for ip in 192.168.11.{13,14,15,16,18,19,20,21,22,23,24,25}; do
    echo "=== Node $ip ==="
    bash scripts/besu-verify-peers.sh "http://${ip}:8545"
    echo ""
done

Expected: Each node should show multiple connected peers.

---

Troubleshooting

No Peers Connected

1. Check firewall: nc -zv <peer-ip> 30303
2. Verify files deployed: pct exec <vmid> -- cat /etc/besu/static-nodes.json
3. Check Besu logs: pct exec <vmid> -- journalctl -u besu-validator -n 50
4. Verify RPC enabled: bash scripts/besu-verify-peers.sh http://<ip>:8545

Invalid Enode Errors

1. Check node ID length: Must be exactly 128 hex characters
2. No padding: Remove trailing zeros
3. Correct IP: Must match actual node IP
4. Unique endpoints: One enode per IP:PORT

Duplicate Enodes

• One node = one enode ID
• Use the enode returned by that node's admin_nodeInfo
• Remove duplicates from allowlist

---

File Locations

On Proxmox containers:

• /etc/besu/static-nodes.json - Validator enodes
• /etc/besu/permissions-nodes.toml - All node enodes
• /etc/besu/config.toml - Besu configuration

Ownership: Files must be owned by besu:besu

---

Key Besu Configuration Flags

# Enable permissions
--permissions-nodes-config-file-enabled=true
--permissions-nodes-config-file=/etc/besu/permissions-nodes.toml

# Static nodes (for faster connection)
--static-nodes-file=/etc/besu/static-nodes.json

# Discovery (can be enabled with permissions)
--discovery-enabled=true

# RPC (must include ADMIN for verification)
--rpc-http-api=ETH,NET,ADMIN,QBFT

---

Verification Checklist

• All enodes have 128-character node IDs
• No duplicate node IDs
• No duplicate IP:PORT endpoints
• Validator IPs correctly mapped
• Files deployed to all containers
• Files owned by besu:besu
• Besu services restarted
• Peers connecting successfully

---

For detailed explanations, see docs/BESU_ALLOWLIST_RUNBOOK.md.