smom-dbis-138/docs/configuration/NETWORK_CONFIGURATION_GUIDE.md

Network Configuration Guide

Last Updated: 2025-01-27
Status: Active
Purpose: Network and Besu configuration setup

Overview

This guide describes how to use the interactive configuration tool to set up all necessary configuration files for the Besu network.

Related Documentation:

• Azure/Cloudflare Environment Setup - For Azure and Cloudflare environment variables
• Contract Deployment Environment Setup - For contract deployment environment variables

Table of Contents

• Overview
• Quick Start
  • Basic Configuration
  • Advanced Configuration
• Configuration Steps
  • 1. Genesis Block Configuration
  • 2. Network Configuration
  • 3. Besu Node Configuration
  • 4. Deployment Configuration
  • 5. Advanced Configuration
• Generated Files
  • Core Configuration
  • Infrastructure Configuration
  • Advanced Configuration
  • Documentation
• Backup
• Validation
• Next Steps
• Troubleshooting
  • Configuration Tool Not Running
  • Invalid Configuration Values
  • Missing Configuration Files
  • Backup Restoration
• Best Practices
• Examples
  • Basic Configuration
  • Advanced Configuration
  • Custom Configuration
• References

Quick Start

Basic Configuration

Run the basic configuration tool:

./scripts/configure-network.sh

This will:

1. Backup existing configuration files
2. Prompt for all necessary configuration values
3. Generate all configuration files
4. Create a configuration summary

Advanced Configuration

For advanced options (security, monitoring, backups, etc.):

./scripts/configure-network-advanced.sh

Configuration Steps

1. Genesis Block Configuration

The tool will prompt for:

• Chain ID: Unique identifier for your network (default: 138)
• Block Period: Time between blocks in seconds (default: 2)
• Epoch Length: Number of blocks in an epoch (default: 30000)
• Request Timeout: Timeout for consensus requests (default: 10 seconds)
• Gas Limit: Maximum gas per block (default: 0x1c9c380)
• Validators: Validator addresses (will be updated after key generation)
• Pre-allocated Accounts: Accounts with initial balances

2. Network Configuration

The tool will prompt for:

• Cluster Name: Name of your Kubernetes cluster
• Resource Group: Azure resource group name
• Location: Azure region
• VNet Address Space: CIDR notation for VNet
• Subnets: CIDR notation for each subnet (validators, sentries, RPC, AKS)
• Node Counts: Number of validators, sentries, and RPC nodes
• VM Sizes: VM sizes for each node type
• Ports: P2P, RPC HTTP, RPC WebSocket, and metrics ports

3. Besu Node Configuration

The tool will prompt for:

• Sync Mode: FULL, FAST, or SNAP
• RPC Configuration: Enable/disable RPC, host, port
• WebSocket Configuration: Enable/disable WebSocket, host, port
• CORS Origins: Allowed CORS origins (for RPC nodes)
• Host Allowlist: Allowed hosts (for RPC nodes)
• JVM Options: JVM memory and options for each node type

4. Deployment Configuration

The tool will prompt for:

• Deployment Type: AKS, VM, or both
• VM Configuration: VM Scale Sets, regions, SSH keys
• Key Vault: Key Vault name and settings
• Monitoring: Enable/disable monitoring components
• Blockscout: Enable/disable Blockscout explorer

5. Advanced Configuration (Advanced Tool Only)

The advanced tool also prompts for:

• Security: Network Policies, RBAC, Pod Security, WAF
• Key Management: Azure Key Vault, key rotation
• Access Control: IP whitelisting, admin IPs
• Monitoring: Prometheus, Grafana, Loki, Alertmanager
• Backups: Backup frequency, retention, storage
• Oracle: Oracle publisher configuration

Generated Files

The configuration tool generates the following files:

Core Configuration

• config/genesis.json - Genesis block configuration
• config/validators/besu-config.toml - Validator node configuration
• config/sentries/besu-config.toml - Sentry node configuration
• config/rpc/besu-config.toml - RPC node configuration
• config/permissions-nodes.toml - Node permissions
• config/permissions-accounts.toml - Account permissions
• config/static-nodes.json - Static nodes configuration

Infrastructure Configuration

• terraform/terraform.tfvars - Terraform variables
• helm/besu-network/values.yaml - Helm values

Advanced Configuration (Advanced Tool Only)

• k8s/network-policies/default-deny.yaml - Network Policies
• monitoring/prometheus/prometheus.yml - Prometheus configuration
• scripts/backup/backup-config.json - Backup configuration

Documentation

• CONFIG_SUMMARY.md - Configuration summary

Backup

Before generating new configuration files, the tool automatically backs up existing files to .config-backup/ directory.

To restore from backup:

cp -r .config-backup/* .

Validation

The configuration tool validates:

• Chain ID: Must be between 1 and 2147483647
• IP Addresses: Must be valid IPv4 addresses
• CIDR Notation: Must be valid CIDR notation
• Ports: Must be between 1 and 65535
• Hex Values: Must be valid hexadecimal values

Next Steps

After running the configuration tool:

1. Generate Validator Keys:

   ./scripts/key-management/generate-validator-keys.sh <count>
   

2. Generate Proper Genesis:

   ./scripts/generate-genesis-proper.sh
   

   This will update genesis.json with proper extraData using validator keys.

3. Review Configuration:

   • Review CONFIG_SUMMARY.md
   • Review generated configuration files
   • Update permissions-nodes.toml with node enodes after deployment
   • Update static-nodes.json with node enodes after deployment

4. Deploy Infrastructure:

   cd terraform
   terraform init
   terraform plan
   terraform apply
   

5. Deploy Kubernetes Resources:

   kubectl apply -k k8s/base
   helm install besu-validators ./helm/besu-network -f helm/besu-network/values.yaml -n besu-network
   

Troubleshooting

Configuration Tool Not Running

Issue: Python script not executing

Solution:

• Ensure Python 3.8+ is installed: python3 --version
• Make script executable: chmod +x scripts/configure-network.sh
• Run directly: python3 scripts/configure-network.py

Invalid Configuration Values

Issue: Configuration tool rejects valid values

Solution:

• Check validation rules in the tool
• Ensure values are in correct format (hex, decimal, CIDR, etc.)
• Review error messages for specific requirements

Missing Configuration Files

Issue: Some configuration files are not generated

Solution:

• Check if advanced options are enabled (use advanced tool)
• Review configuration summary for missing files
• Manually create missing files if needed

Backup Restoration

Issue: Need to restore from backup

Solution:

# Restore all files
cp -r .config-backup/* .

# Restore specific file
cp .config-backup/config/genesis.json config/genesis.json

Best Practices

1. Review Before Deploying: Always review generated configuration files before deploying
2. Backup First: The tool automatically backs up, but you can also manually backup
3. Validate Configuration: Use validation scripts to verify configuration
4. Update After Deployment: Update permissions and static nodes after deployment
5. Document Changes: Document any manual changes to configuration files

Examples

Basic Configuration

./scripts/configure-network.sh

Follow the prompts to configure:

• Chain ID: 138
• Block period: 2 seconds
• 4 validators, 3 sentries, 3 RPC nodes
• AKS deployment
• Basic monitoring

Advanced Configuration

./scripts/configure-network-advanced.sh

Follow the prompts to configure:

• All basic options
• Security policies
• Advanced monitoring
• Backup configuration
• Oracle publisher

Custom Configuration

# Edit configuration directly
vi config/genesis.json
vi terraform/terraform.tfvars
vi helm/besu-network/values.yaml

References

• Besu Configuration
• Terraform Documentation
• Helm Documentation
• Kubernetes Documentation