aitbc/docs/10_plan/firewall-clarification-summary.md

Firewall Clarification: AITBC Containers Use Firehol, Not UFW

🎯 Update Summary

Action: Clarified that AITBC servers run in incus containers on at1 host, which uses firehol for firewall management, not ufw in containers

Date: March 4, 2026

Reason: Correct documentation to reflect actual infrastructure setup

---

✅ Changes Made

1. Main Deployment Guide Updated

aitbc.md - Primary deployment documentation:

### **Network Requirements**
- **Ports**: 8000-8003 (Core Services), 8010-8016 (Enhanced Services) (must be available)
- **Firewall**: Configure to allow AITBC service ports
+ **Firewall**: Managed by firehol on at1 host (container networking handled by incus)
- **SSL/TLS**: Recommended for production deployments

Security Configuration Section:

#### 4.1 Security Configuration
```bash
- # Configure firewall
- # Core Services (8000+)
- sudo ufw allow 8000/tcp  # Coordinator API
- sudo ufw allow 8001/tcp  # Exchange API
- sudo ufw allow 8002/tcp  # Blockchain Node
- sudo ufw allow 8003/tcp  # Blockchain RPC
- 
- # Enhanced Services (8010+)
- sudo ufw allow 8010/tcp  # Multimodal GPU
- sudo ufw allow 8011/tcp  # GPU Multimodal
- sudo ufw allow 8012/tcp  # Modality Optimization
- sudo ufw allow 8013/tcp  # Adaptive Learning
- sudo ufw allow 8014/tcp  # Marketplace Enhanced
- sudo ufw allow 8015/tcp  # OpenClaw Enhanced
- sudo ufw allow 8016/tcp  # Web UI
- 
# Secure sensitive files
+ # Note: AITBC servers run in incus containers on at1 host
+ # Firewall is managed by firehol on at1, not ufw in containers
+ # Container networking is handled by incus with appropriate port forwarding
+ 
+ # Secure sensitive files
chmod 600 /opt/aitbc/apps/coordinator-api/.env
chmod 600 /opt/aitbc/apps/coordinator-api/aitbc_coordinator.db

2. Requirements Validation System Updated

requirements-validation-system.md - Validation system documentation:

#### **Network Requirements**
- **Ports**: 8000-8003 (Core Services), 8010-8016 (Enhanced Services) (must be available)
- **Firewall**: Configurable for AITBC ports
+ **Firewall**: Managed by firehol on at1 host (container networking handled by incus)
- **SSL/TLS**: Required for production
- **Bandwidth**: 100Mbps+ recommended

Configuration Section:

network:
    required_ports:
      # Core Services (8000+)
      - 8000  # Coordinator API
      - 8001  # Exchange API
      - 8002  # Blockchain Node
      - 8003  # Blockchain RPC
      
      # Enhanced Services (8010+)
      - 8010  # Multimodal GPU
      - 8011  # GPU Multimodal
      - 8012  # Modality Optimization
      - 8013  # Adaptive Learning
      - 8014  # Marketplace Enhanced
      - 8015  # OpenClaw Enhanced
      - 8016  # Web UI
-   firewall_required: true
+   firewall_managed_by: "firehol on at1 host"
+   container_networking: "incus"
    ssl_required: true
    minimum_bandwidth_mbps: 100

3. Validation Script Updated

validate-requirements.sh - Requirements validation script:

    if [ ${#OCCUPIED_PORTS[@]} -gt 0 ]; then
        WARNINGS+=("Ports ${OCCUPIED_PORTS[*]} are already in use")
    fi
    
-   # Check firewall status
-   if command -v ufw &> /dev/null; then
-       UFW_STATUS=$(ufw status | head -1)
-       echo "Firewall Status: $UFW_STATUS"
-   fi
-   
+   # Note: AITBC containers use incus networking with firehol on at1 host
+   # This validation is for development environment only
+   echo -e "${BLUE}ℹ️  Note: Production containers use incus networking with firehol on at1 host${NC}"
+   
    echo -e "${GREEN}✅ Network requirements check passed${NC}"

4. Comprehensive Summary Updated

requirements-updates-comprehensive-summary.md - Complete summary:

### **🌐 Network Requirements**
- **Ports**: 8000-8003 (Core Services), 8010-8016 (Enhanced Services) (must be available)
- **Firewall**: Configurable for AITBC ports
+ **Firewall**: Managed by firehol on at1 host (container networking handled by incus)
- **SSL/TLS**: Required for production
- **Bandwidth**: 100Mbps+ recommended

---

📊 Infrastructure Architecture Clarification

Before Clarification

Misconception:
- AITBC containers use ufw for firewall management
- Individual container firewall configuration required
- Port forwarding managed within containers

After Clarification

Actual Architecture:
┌──────────────────────────────────────────────┐
│  at1 Host (Debian 13 Trixie)                 │
│  ┌────────────────────────────────────────┐  │
│  │  incus containers (aitbc, aitbc1)       │  │
│  │  - No internal firewall (ufw)           │  │
│  │  - Networking handled by incus           │  │
│  │  - Firewall managed by firehol on host  │  │
│  │  - Port forwarding configured on host    │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  firehol configuration:                      │
│  - Port forwarding: 8000, 8001, 8002, 8003 │
│  - Port forwarding: 8010-8016               │
│  - SSL termination at host level           │
│  - Container network isolation              │
└──────────────────────────────────────────────┘

---

🎯 Benefits Achieved

✅ Documentation Accuracy

• Correct Architecture: Reflects actual incus container setup
• Firewall Clarification: No ufw in containers, firehol on host
• Network Management: Proper incus networking documentation
• Security Model: Accurate security boundaries

✅ Developer Understanding

• Clear Architecture: Developers understand container networking
• No Confusion: No misleading ufw commands for containers
• Proper Guidance: Correct firewall management approach
• Deployment Clarity: Accurate deployment procedures

✅ Operational Excellence

• Correct Procedures: Proper firewall management on host
• Container Isolation: Understanding of incus network boundaries
• Port Management: Accurate port forwarding documentation
• Security Boundaries: Clear security model

---

📋 Container Architecture Details

🏗️ Container Setup

# at1 host runs incus with containers
# Containers: aitbc (10.1.223.93), aitbc1 (10.1.223.40)
# Networking: incus bridge with NAT
# Firewall: firehol on host, not ufw in containers

# Container characteristics:
- No internal firewall (ufw not used)
- Network interfaces managed by incus
- Port forwarding configured on host
- Isolated network namespaces

🔥 Firehol Configuration

# on at1 host (not in containers)
# firehol handles port forwarding to containers
# Example configuration:
interface any world
    policy drop
    protection strong
    server "ssh" accept
    server "http" accept
    server "https" accept
    
    # Forward to aitbc container
    router aitbc inface eth0 outface incus-aitbc
        route to 10.1.223.93
        server "8000" accept  # Coordinator API
        server "8001" accept  # Exchange API
        server "8002" accept  # Blockchain Node
        server "8003" accept  # Blockchain RPC
        server "8010" accept  # Multimodal GPU
        server "8011" accept  # GPU Multimodal
        server "8012" accept  # Modality Optimization
        server "8013" accept  # Adaptive Learning
        server "8014" accept  # Marketplace Enhanced
        server "8015" accept  # OpenClaw Enhanced
        server "8016" accept  # Web UI

🐳 Incus Networking

# Container networking handled by incus
# No need for ufw inside containers
# Port forwarding managed at host level
# Network isolation between containers

# Container network interfaces:
# eth0: incus bridge interface
# lo: loopback interface
# No direct internet access (NAT through host)

---

🔄 Impact Assessment

✅ Documentation Impact

• Accuracy: Documentation now matches actual setup
• Clarity: No confusion about firewall management
• Guidance: Correct procedures for network configuration
• Architecture: Proper understanding of container networking

✅ Development Impact

• No Misleading Commands: Removed ufw commands for containers
• Proper Focus: Developers focus on application, not container networking
• Clear Boundaries: Understanding of host vs container responsibilities
• Correct Approach: Proper development environment setup

✅ Operations Impact

• Firewall Management: Clear firehol configuration on host
• Container Management: Understanding of incus networking
• Port Forwarding: Accurate port forwarding documentation
• Security Model: Proper security boundaries

---

📞 Support Information

✅ Container Network Verification

# On at1 host (firehol management)
sudo firehol status                    # Check firehol status
sudo incus list                       # List containers
sudo incus exec aitbc -- ip addr show  # Check container network
sudo incus exec aitbc -- netstat -tlnp # Check container ports

# Port forwarding verification
curl -s https://aitbc.bubuit.net/api/v1/health  # Should work
curl -s http://127.0.0.1:8000/v1/health         # Host proxy

✅ Container Internal Verification

# Inside aitbc container (no ufw)
ssh aitbc-cascade
ufw status                            # Should show "inactive" or not installed
netstat -tlnp | grep -E ':(8000|8001|8002|8003|8010|8011|8012|8013|8014|8015|8016)'
# Should show services listening on all interfaces

✅ Development Environment Notes

# Development validation script updated
./scripts/validate-requirements.sh
# Now includes note about incus networking with firehol

# No need to configure ufw in containers
# Focus on application configuration
# Network handled by incus and firehol

---

🎉 Clarification Success

✅ Firewall Clarification Complete:

• Removed misleading ufw commands for containers
• Added correct firehol documentation
• Clarified incus networking architecture
• Updated all relevant documentation

✅ Benefits Achieved:

• Accurate documentation of actual setup
• Clear understanding of container networking
• Proper firewall management guidance
• No confusion about security boundaries

✅ Quality Assurance:

• All documentation updated consistently
• No conflicting information
• Clear architecture explanation
• Proper verification procedures

---

🚀 Final Status

🎯 Clarification Status: ✅ COMPLETE AND VERIFIED

📊 Success Metrics:

• Documentation Updated: 4 files updated
• Misleading Commands Removed: All ufw commands for containers
• Architecture Clarified: incus + firehol model documented
• Validation Updated: Script notes container networking

🔍 Verification Complete:

• Documentation matches actual infrastructure
• No conflicting firewall information
• Clear container networking explanation
• Proper security boundaries documented

🚀 Firewall clarification complete - AITBC containers use firehol on at1, not ufw!

---

Status: ✅ COMPLETE AND VERIFIED
Last Updated: 2026-03-04
Maintainer: AITBC Development Team