d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
3f76bc950779f8c1a4403abddb952cdbce5fa420
proxmox/docs/04-configuration/BESU_PATH_REFERENCE.md
defiQUG fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
docs: Ledger Live integration, contract deploy learnings, NEXT_STEPS updates 
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands
- CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround
- CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check
- NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere
- MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates
- LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 15:46:57 -08:00

9.0 KiB
Raw Blame History

Besu Path Reference Documentation

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

Date: 2026-01-17
Purpose: Comprehensive reference for file paths used in Besu configuration files

Overview

Besu configuration files reference different directory structures depending on node type and deployment method. This document maps each path configuration option to its expected location and explains the path strategy.

Path Configuration Options

data-path

Specifies the root directory for Besu runtime data (database, node keys, etc.)

genesis-file

Location of the genesis block configuration file

static-nodes-file

Location of the static nodes JSON file (list of known peers)

permissions-nodes-config-file

Location of the node permissioning configuration file

permissions-accounts-config-file

Location of the account permissioning configuration file (validators only)

Path Structure by Node Type

Validator Nodes

Configuration Pattern: Simple, flat structure

  • data-path: /data
  • genesis-file: /config/genesis.json
  • static-nodes-file: /config/static-nodes.json
  • permissions-nodes-config-file: /config/permissions-nodes.toml
  • permissions-accounts-config-file: /config/permissions-accounts.toml

Rationale:

  • Validators have simpler deployment (no public access)
  • Flat structure easier to manage for consensus-critical nodes
  • Isolated paths for security

Example Config:

data-path="/data"
genesis-file="/config/genesis.json"
static-nodes-file="/config/static-nodes.json"
permissions-nodes-config-file="/config/permissions-nodes.toml"
permissions-accounts-config-file="/config/permissions-accounts.toml"

File Locations on Validator Nodes:

/data/
  └── database/          # Blockchain database (created by Besu)
  └── nodekey            # Node private key (generated by Besu)

/config/
  └── genesis.json
  └── static-nodes.json
  └── permissions-nodes.toml
  └── permissions-accounts.toml
  └── config-validator.toml

RPC Nodes

Configuration Pattern: Standard Besu structure

  • data-path: /data/besu or /var/lib/besu
  • genesis-file: /genesis/genesis.json
  • static-nodes-file: /var/lib/besu/static-nodes.json or /genesis/static-nodes.json
  • permissions-nodes-config-file: /var/lib/besu/permissions/permissions-nodes.toml (Besu expects TOML; do not use .json)

Rationale:

  • Standard Besu directory structure
  • Separation of data and configuration
  • Consistent with deployment tooling

Example Config (Core RPC):

data-path="/data/besu"
genesis-file="/genesis/genesis.json"
static-nodes-file="/var/lib/besu/static-nodes.json"
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

File Locations on RPC Nodes:

/data/besu/  (or /var/lib/besu/)
  └── database/          # Blockchain database
  └── nodekey            # Node private key

/var/lib/besu/
  └── permissions/
      └── permissions-nodes.toml
  └── static-nodes.json

/genesis/
  └── genesis.json

Sentry Nodes

Configuration Pattern: Standard Besu structure (same as RPC)

  • data-path: /data/besu
  • genesis-file: /genesis/genesis.json
  • static-nodes-file: /var/lib/besu/static-nodes.json
  • permissions-nodes-config-file: /var/lib/besu/permissions/permissions-nodes.toml

Rationale:

  • Same structure as RPC nodes for consistency
  • Archive nodes require organized data structure
  • Standard Besu deployment patterns

Example Config:

data-path="/data/besu"
genesis-file="/genesis/genesis.json"
static-nodes-file="/var/lib/besu/static-nodes.json"
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

File Locations on Sentry Nodes:

/data/besu/
  └── database/          # Full archive database
  └── nodekey            # Node private key

/var/lib/besu/
  └── permissions/
      └── permissions-nodes.toml
  └── static-nodes.json

/genesis/
  └── genesis.json

Path Variants in Configurations

Variant 1: Validator Pattern

data-path="/data"
genesis-file="/config/genesis.json"
static-nodes-file="/config/static-nodes.json"
permissions-nodes-config-file="/config/permissions-nodes.toml"

Variant 2: RPC/Sentry Pattern (Standard Besu)

data-path="/data/besu"
genesis-file="/genesis/genesis.json"
static-nodes-file="/var/lib/besu/static-nodes.json"
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

Variant 3: Alternative RPC Pattern

data-path="/var/lib/besu"
genesis-file="/genesis/genesis.json"
static-nodes-file="/var/lib/besu/static-nodes.json"
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

Current Configuration Files Path Usage

Validator Configs

  • smom-dbis-138/config/config-validator.toml: Uses /data and /config
  • smom-dbis-138-proxmox/templates/besu-configs/config-validator.toml: Uses /data/besu and /genesis (template variant)

RPC Configs

  • config-rpc-core.toml: Uses /data/besu and /var/lib/besu/permissions/
  • config-rpc-public.toml: Uses /data/besu and /permissions/ or /genesis/
  • config-rpc-perm.toml: Uses /data/besu and /var/lib/besu/permissions/
  • config-rpc-thirdweb.toml: Uses /data/besu and /permissions/ or /genesis/
  • config-rpc-4.toml: Uses /var/lib/besu and /genesis/
  • Other RPC configs: Variants of above patterns

Sentry Configs

  • config-sentry.toml: Uses /data/besu and /var/lib/besu/permissions/

Path Consistency Recommendations

Current State

  • ✅ Validators consistently use /data and /config
  • ⚠️ RPC nodes use varying paths (/data/besu vs /var/lib/besu)
  • ⚠️ Permissions files use different formats (JSON vs TOML) and locations

Recommendations

1. Standardize RPC/Sentry Paths

Recommended:

data-path="/data/besu"
genesis-file="/genesis/genesis.json"
static-nodes-file="/var/lib/besu/static-nodes.json"
permissions-nodes-config-file="/var/lib/besu/permissions/permissions-nodes.toml"

2. Maintain Validator Path Pattern

Keep validators with their simpler structure:

data-path="/data"
genesis-file="/config/genesis.json"
static-nodes-file="/config/static-nodes.json"
permissions-nodes-config-file="/config/permissions-nodes.toml"

3. Document Deviations

If different paths are required for specific nodes:

  • Document the reason for deviation
  • Update deployment scripts accordingly
  • Ensure consistency within node type

Deployment Considerations

Directory Creation

When deploying Besu nodes, ensure all referenced directories exist:

Validators

mkdir -p /data /config
chown besu:besu /data /config

RPC/Sentry Nodes

mkdir -p /data/besu /genesis /var/lib/besu/{permissions,static-nodes}
chown besu:besu /data/besu /var/lib/besu /genesis

File Permissions

  • Configuration files: 644 (readable by Besu user)
  • Node keys: 600 (readable only by Besu user)
  • Database directory: 700 (accessible only by Besu user)

Path Validation

When validating configurations, check:

  1. ✅ data-path is specified and absolute
  2. ✅ genesis-file path is absolute and file exists (or will be deployed)
  3. ✅ static-nodes-file path is absolute
  4. ✅ permissions-nodes-config-file path is absolute and file exists (or will be deployed)
  5. ✅ Paths match expected structure for node type

Migration Notes

If migrating from one path structure to another:

  1. Backup existing data: Copy database and keys before migration
  2. Update configs: Modify path references in configuration files
  3. Update deployment scripts: Ensure scripts create correct directories
  4. Update file locations: Move files to new locations if needed
  5. Test deployment: Verify paths work on test node first

Related Documentation

  • docs/05-network/BESU_FIREWALL_RULES.md - Network configuration
  • docs/04-configuration/BESU_CONFIGURATION_GUIDE.md - Configuration reference
  • docs/06-besu/BESU_NODES_FILE_REFERENCE.md - File locations reference

Summary Table

Node Type data-path genesis-file static-nodes-file permissions-nodes
Validator /data /config/genesis.json /config/static-nodes.json /config/permissions-nodes.toml
RPC /data/besu /genesis/genesis.json /var/lib/besu/static-nodes.json /var/lib/besu/permissions/permissions-nodes.toml
Sentry /data/besu /genesis/genesis.json /var/lib/besu/static-nodes.json /var/lib/besu/permissions/permissions-nodes.toml

Note: Some RPC configs use variant paths (/var/lib/besu for data-path, /permissions/ for permissions). These are documented in individual config files.

Last Updated: 2026-01-17
Status: Reference Documentation

Reference in New Issue View Git Blame Copy Permalink