fbda1b4beb
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- 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>
307 lines
9.0 KiB
Markdown
307 lines
9.0 KiB
Markdown
# 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**:
|
|
```toml
|
|
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):
|
|
```toml
|
|
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**:
|
|
```toml
|
|
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**:
|
|
```toml
|
|
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:
|
|
```toml
|
|
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
|
|
```bash
|
|
mkdir -p /data /config
|
|
chown besu:besu /data /config
|
|
```
|
|
|
|
#### RPC/Sentry Nodes
|
|
```bash
|
|
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
|