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](AZURE_CLOUDFLARE_ENV_SETUP.md) - For Azure and Cloudflare environment variables
> - [Contract Deployment Environment Setup](CONTRACT_DEPLOYMENT_ENV_SETUP.md) - For contract deployment environment variables

## Table of Contents

- [Overview](#overview)
- [Quick Start](#quick-start)
  - [Basic Configuration](#basic-configuration)
  - [Advanced Configuration](#advanced-configuration)
- [Configuration Steps](#configuration-steps)
  - [1. Genesis Block Configuration](#1-genesis-block-configuration)
  - [2. Network Configuration](#2-network-configuration)
  - [3. Besu Node Configuration](#3-besu-node-configuration)
  - [4. Deployment Configuration](#4-deployment-configuration)
  - [5. Advanced Configuration](#5-advanced-configuration-advanced-tool-only)
- [Generated Files](#generated-files)
  - [Core Configuration](#core-configuration)
  - [Infrastructure Configuration](#infrastructure-configuration)
  - [Advanced Configuration](#advanced-configuration-advanced-tool-only-1)
  - [Documentation](#documentation)
- [Backup](#backup)
- [Validation](#validation)
- [Next Steps](#next-steps)
- [Troubleshooting](#troubleshooting)
  - [Configuration Tool Not Running](#configuration-tool-not-running)
  - [Invalid Configuration Values](#invalid-configuration-values)
  - [Missing Configuration Files](#missing-configuration-files)
  - [Backup Restoration](#backup-restoration)
- [Best Practices](#best-practices)
- [Examples](#examples)
  - [Basic Configuration](#basic-configuration-1)
  - [Advanced Configuration](#advanced-configuration-1)
  - [Custom Configuration](#custom-configuration)
- [References](#references)

## Quick Start

### Basic Configuration

Run the basic configuration tool:

```bash
./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.):

```bash
./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:

```bash
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**:
   ```bash
   ./scripts/key-management/generate-validator-keys.sh <count>
   ```

2. **Generate Proper Genesis**:
   ```bash
   ./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**:
   ```bash
   cd terraform
   terraform init
   terraform plan
   terraform apply
   ```

5. **Deploy Kubernetes Resources**:
   ```bash
   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**:
```bash
# 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

```bash
./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

```bash
./scripts/configure-network-advanced.sh
```

Follow the prompts to configure:
- All basic options
- Security policies
- Advanced monitoring
- Backup configuration
- Oracle publisher

### Custom Configuration

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

## References

- [Besu Configuration](https://besu.hyperledger.org/stable/Reference/CLI/CLI-Syntax/)
- [Terraform Documentation](https://www.terraform.io/docs)
- [Helm Documentation](https://helm.sh/docs/)
- [Kubernetes Documentation](https://kubernetes.io/docs/)