# 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