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>
315 lines
9.5 KiB
Markdown
315 lines
9.5 KiB
Markdown
# Besu Firewall Rules Documentation
|
|
|
|
**Last Updated:** 2026-01-31
|
|
**Document Version:** 1.0
|
|
**Status:** Active Documentation
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Since Besu v23.10.0+, the `rpc-http-host-allowlist` option has been deprecated. Firewall rules should be used instead to control access to Besu RPC endpoints. This document provides firewall configuration templates and best practices.
|
|
|
|
---
|
|
|
|
## Port Requirements
|
|
|
|
### Common Ports
|
|
|
|
| Port | Protocol | Purpose | Node Types |
|
|
|------|----------|---------|------------|
|
|
| **30303** | TCP/UDP | P2P networking | All nodes |
|
|
| **8545** | TCP | HTTP JSON-RPC | RPC, Sentry |
|
|
| **8546** | TCP | WebSocket JSON-RPC | RPC, Sentry |
|
|
| **9545** | TCP | Metrics (Prometheus) | All nodes |
|
|
|
|
### Validator Nodes
|
|
- **P2P (30303)**: Internal network only (sentries)
|
|
- **Metrics (9545)**: Internal network only
|
|
- **RPC**: Disabled (no ports needed)
|
|
|
|
### Sentry Nodes
|
|
- **P2P (30303)**: Open to external and internal peers
|
|
- **RPC (8545, 8546)**: Internal network only
|
|
- **Metrics (9545)**: Internal network only
|
|
|
|
### RPC Nodes
|
|
- **P2P (30303)**: Internal network only (optional, may be disabled)
|
|
- **RPC (8545, 8546)**: Authorized networks only (varies by RPC type)
|
|
- **Metrics (9545)**: Internal network only
|
|
|
|
---
|
|
|
|
## Network IP Ranges
|
|
|
|
### Internal Network
|
|
- **Subnet**: `192.168.11.0/24`
|
|
- **Purpose**: Internal Besu node communication
|
|
- **Access**: All node types allowed
|
|
|
|
### Node Type IP Ranges
|
|
|
|
#### Validators
|
|
- Range: `192.168.11.100` - `192.168.11.104` (VMIDs 1000-1004)
|
|
|
|
#### Sentries
|
|
- Range: `192.168.11.150` - `192.168.11.153` (VMIDs 1500-1503)
|
|
|
|
#### RPC Nodes
|
|
- Range: `192.168.11.250+` (VMIDs 2500+)
|
|
|
|
---
|
|
|
|
## Firewall Configuration Templates
|
|
|
|
### UFW (Ubuntu/Debian)
|
|
|
|
#### Validator Nodes (Internal Only)
|
|
|
|
```bash
|
|
# Allow P2P from internal network (sentries)
|
|
ufw allow from 192.168.11.150/32 to any port 30303 proto tcp comment "Besu P2P from sentries"
|
|
ufw allow from 192.168.11.151/32 to any port 30303 proto tcp comment "Besu P2P from sentries"
|
|
ufw allow from 192.168.11.152/32 to any port 30303 proto tcp comment "Besu P2P from sentries"
|
|
ufw allow from 192.168.11.153/32 to any port 30303 proto tcp comment "Besu P2P from sentries"
|
|
ufw allow from 192.168.11.150/32 to any port 30303 proto udp comment "Besu P2P UDP from sentries"
|
|
ufw allow from 192.168.11.151/32 to any port 30303 proto udp comment "Besu P2P UDP from sentries"
|
|
ufw allow from 192.168.11.152/32 to any port 30303 proto udp comment "Besu P2P UDP from sentries"
|
|
ufw allow from 192.168.11.153/32 to any port 30303 proto udp comment "Besu P2P UDP from sentries"
|
|
|
|
# Allow metrics from internal network (monitoring)
|
|
ufw allow from 192.168.11.0/24 to any port 9545 proto tcp comment "Besu metrics internal"
|
|
|
|
# Deny all other traffic (explicit)
|
|
ufw deny 30303
|
|
ufw deny 9545
|
|
```
|
|
|
|
#### Sentry Nodes (P2P Open, RPC Internal)
|
|
|
|
```bash
|
|
# Allow P2P from anywhere (public peers)
|
|
ufw allow 30303/tcp comment "Besu P2P TCP"
|
|
ufw allow 30303/udp comment "Besu P2P UDP"
|
|
|
|
# Allow RPC from internal network only
|
|
ufw allow from 192.168.11.0/24 to any port 8545 proto tcp comment "Besu HTTP-RPC internal"
|
|
ufw allow from 192.168.11.0/24 to any port 8546 proto tcp comment "Besu WS-RPC internal"
|
|
|
|
# Allow metrics from internal network
|
|
ufw allow from 192.168.11.0/24 to any port 9545 proto tcp comment "Besu metrics internal"
|
|
|
|
# Deny RPC from external
|
|
ufw deny from any to any port 8545 proto tcp comment "Deny external HTTP-RPC"
|
|
ufw deny from any to any port 8546 proto tcp comment "Deny external WS-RPC"
|
|
```
|
|
|
|
#### RPC Core Nodes (Internal Only)
|
|
|
|
```bash
|
|
# Allow P2P from internal network only
|
|
ufw allow from 192.168.11.0/24 to any port 30303 proto tcp comment "Besu P2P internal"
|
|
ufw allow from 192.168.11.0/24 to any port 30303 proto udp comment "Besu P2P UDP internal"
|
|
|
|
# Allow RPC from internal network only
|
|
ufw allow from 192.168.11.0/24 to any port 8545 proto tcp comment "Besu HTTP-RPC internal"
|
|
ufw allow from 192.168.11.0/24 to any port 8546 proto tcp comment "Besu WS-RPC internal"
|
|
|
|
# Allow metrics from internal network
|
|
ufw allow from 192.168.11.0/24 to any port 9545 proto tcp comment "Besu metrics internal"
|
|
|
|
# Deny external access
|
|
ufw deny 30303
|
|
ufw deny 8545
|
|
ufw deny 8546
|
|
ufw deny 9545
|
|
```
|
|
|
|
#### RPC Public Nodes (Authorized Networks)
|
|
|
|
```bash
|
|
# Allow P2P from internal network
|
|
ufw allow from 192.168.11.0/24 to any port 30303 proto tcp comment "Besu P2P internal"
|
|
ufw allow from 192.168.11.0/24 to any port 30303 proto udp comment "Besu P2P UDP internal"
|
|
|
|
# Allow RPC from authorized networks (customize as needed)
|
|
# Example: Allow from specific external IPs or VPN ranges
|
|
# ufw allow from 10.0.0.0/8 to any port 8545 proto tcp comment "Besu RPC VPN"
|
|
# ufw allow from 10.0.0.0/8 to any port 8546 proto tcp comment "Besu WS-RPC VPN"
|
|
|
|
# Allow RPC from internal network
|
|
ufw allow from 192.168.11.0/24 to any port 8545 proto tcp comment "Besu HTTP-RPC internal"
|
|
ufw allow from 192.168.11.0/24 to any port 8546 proto tcp comment "Besu WS-RPC internal"
|
|
|
|
# Allow metrics from internal network only
|
|
ufw allow from 192.168.11.0/24 to any port 9545 proto tcp comment "Besu metrics internal"
|
|
|
|
# Default deny for external RPC
|
|
ufw deny from any to any port 8545 proto tcp comment "Deny external HTTP-RPC"
|
|
ufw deny from any to any port 8546 proto tcp comment "Deny external WS-RPC"
|
|
```
|
|
|
|
---
|
|
|
|
### iptables Rules
|
|
|
|
#### Validator Nodes
|
|
|
|
```bash
|
|
# Allow P2P from sentries (TCP)
|
|
iptables -A INPUT -p tcp -s 192.168.11.150/32 --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p tcp -s 192.168.11.151/32 --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p tcp -s 192.168.11.152/32 --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p tcp -s 192.168.11.153/32 --dport 30303 -j ACCEPT
|
|
|
|
# Allow P2P from sentries (UDP)
|
|
iptables -A INPUT -p udp -s 192.168.11.150/32 --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p udp -s 192.168.11.151/32 --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p udp -s 192.168.11.152/32 --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p udp -s 192.168.11.153/32 --dport 30303 -j ACCEPT
|
|
|
|
# Allow metrics from internal network
|
|
iptables -A INPUT -p tcp -s 192.168.11.0/24 --dport 9545 -j ACCEPT
|
|
|
|
# Deny all other traffic to Besu ports
|
|
iptables -A INPUT -p tcp --dport 30303 -j DROP
|
|
iptables -A INPUT -p udp --dport 30303 -j DROP
|
|
iptables -A INPUT -p tcp --dport 9545 -j DROP
|
|
```
|
|
|
|
#### Sentry Nodes
|
|
|
|
```bash
|
|
# Allow P2P from anywhere
|
|
iptables -A INPUT -p tcp --dport 30303 -j ACCEPT
|
|
iptables -A INPUT -p udp --dport 30303 -j ACCEPT
|
|
|
|
# Allow RPC from internal network only
|
|
iptables -A INPUT -p tcp -s 192.168.11.0/24 --dport 8545 -j ACCEPT
|
|
iptables -A INPUT -p tcp -s 192.168.11.0/24 --dport 8546 -j ACCEPT
|
|
|
|
# Allow metrics from internal network
|
|
iptables -A INPUT -p tcp -s 192.168.11.0/24 --dport 9545 -j ACCEPT
|
|
|
|
# Deny external RPC
|
|
iptables -A INPUT -p tcp --dport 8545 -j DROP
|
|
iptables -A INPUT -p tcp --dport 8546 -j DROP
|
|
```
|
|
|
|
---
|
|
|
|
## Proxmox Firewall Rules
|
|
|
|
If using Proxmox containers, firewall rules can be configured at the Proxmox host level:
|
|
|
|
### Proxmox Firewall Configuration
|
|
|
|
```bash
|
|
# Allow P2P from internal network (validators)
|
|
pct set <vmid> -net0 firewall=1
|
|
pct set <vmid> -net0 firewall=1 -net0 firewall_macfilter=1
|
|
|
|
# Configure rules via Proxmox web UI or API
|
|
# Rules should match UFW/iptables patterns above
|
|
```
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
### 1. Principle of Least Privilege
|
|
- Only open ports that are necessary
|
|
- Restrict access to smallest IP ranges possible
|
|
- Use internal networks for administrative access
|
|
|
|
### 2. Network Segmentation
|
|
- Validators: Isolated, no public access
|
|
- Sentries: P2P public, RPC internal only
|
|
- RPC Nodes: Restrict to authorized networks
|
|
|
|
### 3. Monitoring
|
|
- Monitor firewall logs for unauthorized access attempts
|
|
- Alert on unusual traffic patterns
|
|
- Regular firewall rule audits
|
|
|
|
### 4. Defense in Depth
|
|
- Firewall rules (network layer)
|
|
- CORS configuration (application layer)
|
|
- Authentication/authorization where applicable
|
|
|
|
---
|
|
|
|
## CORS Configuration Reference
|
|
|
|
With firewall rules in place, CORS configuration should align:
|
|
|
|
### Internal RPC Nodes (Core)
|
|
```toml
|
|
rpc-http-cors-origins=["http://192.168.11.0/24","http://localhost","http://127.0.0.1"]
|
|
```
|
|
|
|
### Public RPC Nodes
|
|
```toml
|
|
# Match firewall allowed networks
|
|
rpc-http-cors-origins=["http://authorized-domain.com","http://vpn-network"]
|
|
```
|
|
|
|
### Sentry Nodes (Internal)
|
|
```toml
|
|
rpc-http-cors-origins=["http://192.168.11.0/24","http://localhost"]
|
|
```
|
|
|
|
---
|
|
|
|
## Firewall Testing
|
|
|
|
### Verify Firewall Rules
|
|
|
|
```bash
|
|
# Check UFW status
|
|
ufw status numbered
|
|
|
|
# Check iptables rules
|
|
iptables -L -n -v
|
|
|
|
# Test port accessibility
|
|
# From internal network:
|
|
nc -zv 192.168.11.100 30303 # Should succeed for validators from sentries
|
|
nc -zv 192.168.11.150 8545 # Should succeed from internal network
|
|
nc -zv 192.168.11.150 8545 # Should fail from external network
|
|
|
|
# Test with curl
|
|
curl -v http://192.168.11.150:8545 # Test RPC from internal
|
|
```
|
|
|
|
### Troubleshooting
|
|
|
|
1. **Port not accessible**: Check firewall rules and order
|
|
2. **RPC rejected**: Verify CORS origins match firewall allowed networks
|
|
3. **P2P not connecting**: Ensure UDP and TCP ports open for P2P
|
|
|
|
---
|
|
|
|
## Migration from rpc-http-host-allowlist
|
|
|
|
When migrating from deprecated `rpc-http-host-allowlist`:
|
|
|
|
1. **Remove deprecated option** from configs (already done)
|
|
2. **Configure firewall rules** using templates above
|
|
3. **Update CORS** to match firewall allowed networks
|
|
4. **Test access** from authorized and unauthorized networks
|
|
5. **Monitor logs** for any access issues
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- `docs/04-configuration/BESU_CONFIGURATION_GUIDE.md` - Configuration reference
|
|
- `docs/04-configuration/BESU_CLEANUP_COMPLETE.md` - Deprecated options cleanup
|
|
- Besu documentation: https://besu.hyperledger.org/en/stable/
|
|
|
|
---
|
|
|
|
**Last Updated:** 2026-01-31
|
|
**Status:** Active Documentation
|