proxmox/docs/05-network/RPC_2500_LOCAL_NODES_ONLY.md

# VMID 2500 (Core RPC) - Local/Permissioned Nodes Only Configuration

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation  
**VMID**: 2500  
**IP**: 192.168.11.250  
**Purpose**: Core RPC node restricted to local/permissioned nodes only

---

## Configuration Overview

VMID 2500 is the **Core RPC node** and should **ONLY** connect to local/permissioned nodes on the internal network (192.168.11.0/24).

### Key Configuration Settings

1. **Node Permissioning**: ✅ ENABLED
   - `permissions-nodes-config-file-enabled=true`
   - `permissions-nodes-config-file="/permissions/permissions-nodes.toml"`
   - Only nodes listed in this file can connect

2. **Discovery**: ❌ DISABLED
   - `discovery-enabled=false`
   - Prevents discovery of external nodes
   - Only uses static nodes and permissioned nodes allowlist

3. **Static Nodes**: ✅ Enabled
   - `static-nodes-file="/genesis/static-nodes.json"`
   - Contains only validator nodes (1000-1004)

---

## Permissions Allowlist

The `permissions-nodes.toml` file should contain **ONLY** local network nodes:

### Validators (1000-1004)
- 192.168.11.100 - Validator 1
- 192.168.11.101 - Validator 2
- 192.168.11.102 - Validator 3
- 192.168.11.103 - Validator 4
- 192.168.11.104 - Validator 5

### Sentries (1500-1503)
- 192.168.11.150 - Sentry 1
- 192.168.11.151 - Sentry 2
- 192.168.11.152 - Sentry 3
- 192.168.11.153 - Sentry 4

### RPC Nodes (2500-2502)
- 192.168.11.250 - Core RPC (this node)
- 192.168.11.251 - Permissioned RPC
- 192.168.11.252 - Public RPC

**Total**: 12 nodes (all on 192.168.11.0/24 local network)

---

## Configuration File

**Location**: `/etc/besu/config-rpc-core.toml`

**Key Settings**:
```toml
# Permissioning - ONLY local/permissioned nodes
permissions-nodes-config-file-enabled=true
permissions-nodes-config-file="/permissions/permissions-nodes.toml"

# Discovery - DISABLED for strict control
discovery-enabled=false

# Static nodes - only validators
static-nodes-file="/genesis/static-nodes.json"

# Full RPC APIs enabled (for internal/core infrastructure)
rpc-http-api=["ETH","NET","WEB3","ADMIN","DEBUG","TXPOOL"]
rpc-ws-api=["ETH","NET","WEB3","ADMIN","DEBUG","TXPOOL"]
```

---

## Verification

### Check Permissioning is Enabled
```bash
pct exec 2500 -- grep "permissions-nodes-config-file-enabled" /etc/besu/config-rpc-core.toml
# Should show: permissions-nodes-config-file-enabled=true
```

### Check Discovery is Disabled
```bash
pct exec 2500 -- grep "discovery-enabled" /etc/besu/config-rpc-core.toml
# Should show: discovery-enabled=false
```

### Verify Permissions File Contains Only Local Nodes
```bash
pct exec 2500 -- cat /permissions/permissions-nodes.toml | grep -o "192.168.11\.[0-9]*" | sort -u
# Should show only 192.168.11.x addresses (local network)
```

### Check Connected Peers
```bash
curl -X POST http://192.168.11.250:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":1}' | jq '.result[].remoteAddress'
# Should show only 192.168.11.x addresses
```

---

## Security Benefits

1. **No External Discovery**: With `discovery-enabled=false`, the node cannot discover nodes outside the permissioned allowlist

2. **Strict Allowlisting**: Only nodes explicitly listed in `permissions-nodes.toml` can connect

3. **Local Network Only**: All allowed nodes are on the 192.168.11.0/24 network

4. **Defense in Depth**: Even if discovery were enabled, permissioning would still block unauthorized nodes

---

## Related Documentation

- [RPC Node Types Architecture](./RPC_NODE_TYPES_ARCHITECTURE.md)
- [Besu Allowlist Runbook](../06-besu/BESU_ALLOWLIST_RUNBOOK.md)
- [RPC 2500 Troubleshooting](/docs/09-troubleshooting/RPC_2500_TROUBLESHOOTING.md)

---

**Last Updated**: $(date)