ICN Configuration Management Guide

Version: 1.0
Last Updated: 2025-12-16
Status: Complete

Overview

ICN uses TOML configuration files for all node settings. This guide covers configuration management, validation, and best practices.

Configuration Files

Default Locations

icnd uses one of two modes:

1. Command-line specified config: icnd --config /path/to/config.toml
2. Built-in defaults: if --config is not provided, icnd starts from Config::default() and applies CLI/env overrides.

Note: there is no automatic multi-path config file search order in current icnd.

Example Configuration

See icn/config/icn.toml.example for a fully documented example with available options.

Configuration Validation

Runtime Validation (Primary)

Use icnd --validate-config (same validation logic used at startup):

# Validate a specific config file
icnd --config /path/to/config.toml --validate-config

Validation Tool (Optional/Legacy)

scripts/validate-config.py can be used if you provide a compatible JSON schema:

# Install dependencies
pip install jsonschema toml

# Validate configuration (requires --schema path)
python3 scripts/validate-config.py --schema /path/to/icn-config.schema.json /path/to/config.toml

# Validate with verbose output
python3 scripts/validate-config.py --verbose --schema /path/to/icn-config.schema.json /path/to/config.toml

# Validate JSON configuration
python3 scripts/validate-config.py --format json --schema /path/to/icn-config.schema.json /path/to/config.json

IDE Integration

If you maintain a local JSON schema, configure your IDE to validate TOML files:

VS Code (settings.json):

{
  "evenBetterToml.schema.associations": {
    "icn.toml": "file:///path/to/icn/config/icn-config.schema.json"
  }
}

IntelliJ/PyCharm:

1. Settings → Languages & Frameworks → Schemas and DTDs
2. Add JSON Schema → File
3. Select your local schema file (for example icn-config.schema.json)
4. Add file pattern: **/icn*.toml

Configuration Sections

1. Node Configuration

# Data directory for all node data
data_dir = "/var/lib/icn"

Best Practices:

• Use absolute paths
• Ensure write permissions
• Consider disk space (ledger growth)

2. Network Configuration

[network]
listen_addr = "0.0.0.0:7777"
rpc_port = 5601
mdns_enabled = true
bootstrap_peers = []
min_trust_threshold = 0.1

Security Considerations:

• Set min_trust_threshold >= 0.1 for public networks
• Disable mDNS (mdns_enabled = false) in production
• Use firewall rules to restrict listen_addr

Bootstrap Peers:

bootstrap_peers = [
    "icn://did:icn:z6Mk...@203.0.113.50:7777",
    "icn://did:icn:z6Mk...@203.0.113.51:7777"
]

3. Observability

[observability]
metrics_port = 9100
health_port = 8080
log_level = "info"

Log Levels:

• trace: Very verbose (development only)
• debug: Detailed debugging information
• info: Normal operations (recommended)
• warn: Warning messages only
• error: Errors only (not recommended)

4. Rate Limiting

[rate_limiting]
enabled = true
refill_interval_ms = 100

[rate_limiting.isolated]
max_messages_per_second = 10
burst_capacity = 2

[rate_limiting.known]
max_messages_per_second = 50
burst_capacity = 10

[rate_limiting.partner]
max_messages_per_second = 100
burst_capacity = 20

[rate_limiting.federated]
max_messages_per_second = 200
burst_capacity = 50

Tuning Guidelines:

• Isolated: Strict limits for untrusted peers
• Known: Moderate limits for basic trust
• Partner: Generous limits for collaborators
• Federated: High limits for trusted members

5. Topology (Optional)

[topology]
region = "us-west"
cluster_id = "sfo-1"
role = "edge"

[topology.neighbor_limits]
max_local_cluster = 50
max_regional = 30
max_backbone = 20
max_trusted = 100

[topology.fanout]
local_cluster = 8
regional = 6
global = 4

When to Use:

• Large networks (100+ nodes)
• Geographic distribution
• Bandwidth optimization

When to Skip:

• Small cooperatives (<50 nodes)
• Single geographic location
• Simple deployments

6. Federation

[federation]
enabled = true
network_name = "icn-mainnet"
bootstrap_peer_trust = 0.3
auto_accept_invites = false
min_invite_trust = 0.5
max_federations = 10
announce_public_addr = true

[federation.retry]
max_retries = 5
initial_delay_secs = 1
max_delay_secs = 60
reconnect_interval_secs = 30

Security:

• Set auto_accept_invites = false initially
• Use min_invite_trust >= 0.5 if enabling auto-accept
• Monitor max_federations to prevent exhaustion

7. Gateway API

[gateway]
enabled = true
bind_addr = "127.0.0.1:8080"
token_expiry_hours = 24
challenge_ttl_minutes = 5
jwt_secret = ""  # Use environment variable!

[gateway.rate_limiting]
capacity = 100
refill_rate = 10
cost_per_request = 1

Security Critical:

• ⚠️ NEVER commit jwt_secret to version control
• Use environment variable: ICN_GATEWAY_JWT_SECRET
• Bind to 127.0.0.1 and use reverse proxy
• Enable TLS in reverse proxy (nginx/Apache)

Generate JWT Secret:

openssl rand -base64 32

8. Privacy (Optional)

[privacy]
enabled = true
onion_routing_enabled = true
onion_hops = 2
min_relay_trust = 0.3
topic_encryption_enabled = false
traffic_obfuscation_enabled = false
padding_target = 0
max_delay_ms = 0
cover_traffic_rate = 0

Performance Impact:

• Onion routing: +100-500ms latency per hop
• Traffic obfuscation: +10-50ms latency
• Cover traffic: Bandwidth cost

9. Cooperative

[cooperative]
treasury_did = "did:icn:z6Mk..."
name = "My Cooperative"
description = "A community cooperative"

Environment Variables

Only selected runtime values are read from environment variables in current icnd:

Precedence (highest to lowest):

1. Command-line arguments
2. Configuration file
3. Default values

Environment variables apply only where explicitly supported (for example gateway JWT and OpenTelemetry settings), not as a blanket override for all config fields.

Configuration Templates

Development

data_dir = "./.icn-dev"

[network]
listen_addr = "127.0.0.1:7777"
mdns_enabled = true
min_trust_threshold = 0.0

[observability]
log_level = "debug"

[gateway]
enabled = true
bind_addr = "127.0.0.1:8080"
jwt_secret = "dev-secret-change-in-production"

Production (Small Cooperative)

data_dir = "/var/lib/icn"

[network]
listen_addr = "0.0.0.0:7777"
mdns_enabled = false
bootstrap_peers = ["icn://..."]
min_trust_threshold = 0.1

[observability]
metrics_port = 9100
health_port = 8080
log_level = "info"

[rate_limiting]
enabled = true

[gateway]
enabled = true
bind_addr = "127.0.0.1:8080"
# jwt_secret loaded from environment

[cooperative]
name = "My Coop"

Production (Federated Network)

data_dir = "/var/lib/icn"

[network]
listen_addr = "0.0.0.0:7777"
mdns_enabled = false
bootstrap_peers = ["icn://..."]
min_trust_threshold = 0.3

[observability]
metrics_port = 9100
log_level = "info"

[topology]
region = "us-west"
cluster_id = "sfo-1"
role = "edge"

[federation]
enabled = true
network_name = "icn-mainnet"
auto_accept_invites = false
min_invite_trust = 0.6

[gateway]
enabled = true
bind_addr = "127.0.0.1:8080"
token_expiry_hours = 12

Secrets Management

DO NOT Store Secrets in Config Files

❌ Never do this:

[gateway]
jwt_secret = "my-secret-key"  # INSECURE!

✅ Always do this:

# Set environment variable
export ICN_GATEWAY_JWT_SECRET=$(openssl rand -base64 32)

# Or use systemd EnvironmentFile
# /etc/icn/icnd.env:
ICN_GATEWAY_JWT_SECRET=<generated-secret>

Secrets Management Tools

Kubernetes:

apiVersion: v1
kind: Secret
metadata:
  name: icn-secrets
stringData:
  jwt-secret: <base64-encoded-secret>
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: icnd
    env:
    - name: ICN_GATEWAY_JWT_SECRET
      valueFrom:
        secretKeyRef:
          name: icn-secrets
          key: jwt-secret

HashiCorp Vault:

# Store secret
vault kv put secret/icn/jwt-secret value="$(openssl rand -base64 32)"

# Retrieve and use
export ICN_GATEWAY_JWT_SECRET=$(vault kv get -field=value secret/icn/jwt-secret)

AWS Secrets Manager:

# Store secret
aws secretsmanager create-secret \
  --name icn/jwt-secret \
  --secret-string "$(openssl rand -base64 32)"

# Retrieve in application
aws secretsmanager get-secret-value \
  --secret-id icn/jwt-secret \
  --query SecretString \
  --output text

Configuration Migration

Version Compatibility

ICN follows semantic versioning. Configuration changes:

Migration Checklist

When upgrading ICN:

1. Backup configuration: cp config.toml config.toml.backup
2. Review CHANGELOG: Check for config changes
3. Validate: icnd --config /path/to/config.toml --validate-config
4. Test startup: Start with your target flags in a non-production environment
5. Monitor: Watch logs after upgrade

Troubleshooting

Configuration Not Loading

Symptom: ICN uses default values instead of config

Solutions:

1. Check file path: icnd --config /path/to/config.toml
2. Verify file permissions: ls -l /path/to/config.toml
3. Enable debug logging: icnd --log-level debug

Validation Fails

Symptom: icnd --validate-config reports errors

Solutions:

1. Check for typos in section names
2. Verify data types (string vs. integer)
3. Check required fields are present
4. Review error message carefully

Gateway Won't Start

Symptom: Gateway enabled but not responding

Common Causes:

1. Missing jwt_secret: Set via environment variable
2. Port already in use: Check with netstat -tlnp | grep 8080
3. Firewall blocking: sudo ufw allow 8080/tcp

Network Connectivity Issues

Symptom: No peers connecting

Solutions:

1. Check firewall: sudo ufw status
2. Verify listen_addr is correct
3. Test bootstrap peers: telnet peer.example.com 7777
4. Lower min_trust_threshold temporarily

Best Practices

1. Configuration as Code

• Store configurations in version control
• Use separate configs for dev/staging/prod
• Remove secrets before committing
• Document custom settings

2. Regular Validation

# Add to CI pipeline
icnd --config /path/to/config.toml --validate-config

3. Monitoring

Monitor configuration drift:

• Alert on unexpected changes
• Track configuration versions
• Audit configuration access

4. Documentation

Document custom settings:

# Custom rate limit for our high-traffic network
# Increased after load testing on 2025-12-01
[rate_limiting.partner]
max_messages_per_second = 150  # Was: 100

5. Testing

Test configuration changes:

1. Validate with schema
2. Test in staging environment
3. Monitor metrics after deployment
4. Have rollback plan ready

Appendix: Full Configuration Reference

See icn/config/icn.toml.example for complete reference with all options documented.

Support

• Configuration Issues: https://github.com/InterCooperative-Network/icn/issues
• Security: security@icn.coop
• Documentation: https://icn.coop/docs

Document Version: 1.0
Last Updated: 2025-12-16