ZWall.net Documentation
Complete guide for the Next-Generation eBPF/XDP Firewall System
System Overview
ZWall.net is an enterprise-grade network security solution that leverages eBPF/XDP technology for high-performance packet filtering and centralized management. The system provides real-time threat detection, distributed enforcement, and comprehensive monitoring capabilities.
🚀 High Performance
eBPF/XDP technology delivers sub-microsecond latency and 10+ Gbps throughput with minimal CPU overhead.
🎯 Centralized Management
Manage thousands of agents from a single web interface with real-time policy synchronization.
🔍 Real-time Monitoring
Comprehensive observability with live traffic analysis, security events, and performance metrics.
🛡️ Enterprise Security
Advanced authentication, audit logging, and compliance features for enterprise environments.
Key Capabilities:
- • IPv4/IPv6 packet filtering with CIDR support
- • TCP/UDP port-based access control
- • MAC address filtering and BPDU protection
- • Rate limiting and DDoS mitigation
- • Real-time security event streaming
- • RESTful API for automation and integration
Project Overview
Project Structure
📁 Root Directory
firewall-project/
├── cmd/ # Application entry points
│ ├── agent/ # Agent service main
│ └── manager/ # Manager service main
├── internal/ # Private application code
│ ├── agent/ # Agent-specific logic
│ ├── api/ # REST API handlers
│ ├── auth/ # Authentication & authorization
│ ├── config/ # Configuration management
│ ├── database/ # Database operations
│ ├── manager/ # Manager-specific logic
│ ├── models/ # Data models
│ ├── notification/ # Alert system
│ ├── services/ # Business logic services
│ ├── tc/ # Traffic Control (TC) handling
│ ├── unified/ # Unified interfaces
│ ├── version/ # Version information
│ └── xdp/ # XDP/eBPF integration
├── ebpf/ # eBPF programs
│ ├── firewall.c # Main XDP firewall
│ ├── firewall_egress.c # TC egress firewall
│ ├── firewall_simple.c # Basic firewall
│ └── Makefile # eBPF build system
├── scripts/ # Management scripts
│ ├── setup.sh # Installation script
│ ├── enable-ebpf.sh # eBPF activation
│ ├── rebuild-*.sh # Rebuild scripts
│ ├── system-status.sh # Health monitoring
│ ├── ebpf_monitor.sh # eBPF monitoring
│ └── test_ebpf.sh # eBPF testing
├── config/ # Configuration templates
├── web/ # Web interface assets
└── website-files/ # Documentation
🔧 Build & Development
├── go.mod # Go module definition
├── go.sum # Dependency checksums
├── Makefile # Build automation
├── README.md # Project documentation
├── INSTALLATION_GUIDE.md
├── DEPLOYMENT.md
├── TESTING_GUIDE.md
└── TROUBLESHOOTING_GUIDE.md
⚙️ Configuration Files
config/
├── agent_optimized.yaml # Optimized agent config
├── agent.yml.example # Agent config template
├── manager.yml.example # Manager config template
├── ebpf_config.json # eBPF configuration
└── manager.yaml # Manager configuration
/etc/firewall-manager/ # Runtime manager config
/etc/firewall-agent/ # Runtime agent config
📊 Database Schema
PostgreSQL Database:
├── rules # Firewall rules
├── agents # Registered agents
├── security_logs # Security events
├── agent_rules # Agent-rule assignments
├── users # System users
├── sessions # User sessions
└── audit_logs # Audit trail
Technology Stack
🔥 eBPF/XDP Engine
High-performance packet processing
- • eBPF programs in C
- • XDP for ingress filtering
- • Traffic Control (TC) for egress
- • cilium/ebpf Go library
- • Kernel 4.18+ support
🐹 Go Backend
Concurrent and efficient services
- • Go 1.19+ runtime
- • Gin web framework
- • GORM ORM
- • JWT authentication
- • Concurrent processing
🐘 PostgreSQL Database
ACID-compliant data storage
- • PostgreSQL 12+
- • Connection pooling
- • Advanced indexing
- • JSONB for flexible data
- • ACID transactions
🌐 Web Interface
Modern responsive UI
- • Vue.js 3 framework
- • Tailwind CSS
- • RESTful API integration
- • Real-time dashboards
- • Mobile responsive
🔒 Security Features
Enterprise-grade security
- • TLS 1.3 encryption
- • JWT token authentication
- • Role-based access control
- • Audit logging
- • Secure agent registration
📦 Build System
Automated compilation and deployment
- • GNU Make build system
- • clang/LLVM for eBPF
- • Go build tools
- • Systemd integration
- • Automated testing
Component Descriptions
Manager Service
Central control and management
- • Web interface serving
- • REST API endpoints
- • Agent orchestration
- • Policy management
- • Security event aggregation
- • Database operations
Agent Service
Distributed enforcement
- • eBPF program loading
- • Rule enforcement
- • Event collection
- • Health monitoring
- • Manager communication
- • Local logging
eBPF Programs
Kernel-level packet processing
- • XDP ingress filtering
- • TC egress filtering
- • Real-time rule updates
- • Performance monitoring
- • Event generation
- • Memory-efficient maps
Web Interface
User management console
- • Dashboard views
- • Rule configuration
- • Agent monitoring
- • Security event display
- • System settings
- • User management
Development Workflow
# 1. Development Setup
git clone https://github.com/your-org/firewall-project.git
cd firewall-project
make setup-dev
# 2. Build the project
make build
# 3. Run tests
make test
# 4. Start development services
make dev-up
# 5. Access development interface
# Manager: https://localhost:8443
# API: https://localhost:8443/api/v1
# Documentation: https://localhost:8443/docs
# 6. Development commands
make clean # Clean build artifacts
make ebpf-clean # Clean eBPF objects
make fmt # Format code
make lint # Run linters
make docker-build # Build Docker images
Deployment Environments
Development
• Local development setup
• Debug logging enabled
• Hot reload capabilities
• Test databases
• Development certificates
• All services on localhost
Staging
• Pre-production environment
• Production-like configuration
• Limited test data
• Performance monitoring
• Automated deployments
• Staging certificates
Production
• Full production deployment
• High availability setup
• Production certificates
• Comprehensive monitoring
• Backup and recovery
• Security hardening
Docker
• Containerized deployment
• Docker Compose orchestration
• Multi-stage builds
• Volume persistence
• Network isolation
• Easy scaling
Key Dependencies
Runtime Dependencies:
- Linux Kernel: 4.18+ with eBPF and XDP support
- clang/LLVM: 9.0+ for eBPF compilation
- libbpf: eBPF library for userspace interaction
- PostgreSQL: 12+ with PostGIS extension
- systemd: Service management and process supervision
- OpenSSL: TLS certificate generation and validation
Go Module Dependencies:
- gin-gonic/gin: HTTP web framework
- cilium/ebpf: eBPF program loading and management
- lib/pq: PostgreSQL database driver
- dgrijalva/jwt-go: JWT token handling
- gorilla/websocket: Real-time communication
- spf13/viper: Configuration management
System Architecture
Core Components
Manager (Central Control)
Web interface, API server, policy management, and agent orchestration
Agents (Distributed Enforcement)
eBPF program execution, local monitoring, and event forwarding
Database (Persistent Storage)
Configuration, policies, security logs, and audit trails
Technology Stack
eBPF/XDP Engine
Kernel-level packet processing with zero-copy performance
Go Backend
Concurrent processing, efficient memory management
PostgreSQL Database
ACID compliance, advanced querying, and indexing
Data Flow Architecture
Policy Creation: Web UI → Manager API → Database → Agent Sync
Packet Processing: Network Packet → XDP Hook → eBPF Program → Decision (Pass/Drop)
Event Reporting: Agent → Security Event → Manager → Database → Web UI
Monitoring: Agent Metrics → Manager → Real-time Dashboard Updates
Installation Guide
Prerequisites:
- • Linux kernel 5.4+ with eBPF support
- • Root privileges for eBPF operations
- • PostgreSQL 12+ for the database
- • Go 1.19+ for building from source
- • 4GB RAM minimum (8GB recommended)
Quick Start
- Clone the repository and navigate to the project directory
- Install system dependencies
- Configure the database
- Build and install the Manager
- Configure and start the Manager service
- Deploy and configure Agents
- Access the web interface
# 1. Clone repository
git clone https://github.com/zwall-net/zwall.git
cd zwall
# 2. Install dependencies
sudo apt update
sudo apt install -y postgresql postgresql-contrib clang llvm libbpf-dev
# 3. Setup database
sudo -u postgres createdb zwall
sudo -u postgres psql -c "CREATE USER zwall WITH PASSWORD 'secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE zwall TO zwall;"
# 4. Build the system
make build
# 5. Install services
sudo make install
Automated Installation with Scripts
Interactive Setup Script (setup.sh)
The setup.sh script provides an interactive installation process with multiple deployment modes.
🏢 Full System Installation
Complete deployment with Manager, Web Panel, Agent, and Database
# Interactive full installation
sudo ./scripts/setup.sh
# Non-interactive with pre-token
sudo ./scripts/setup.sh --pre-token abc123xyz --manager-url https://manager.example.com:8443
🎯 Core Only Installation
Manager and Web Panel without local Agent
sudo ./scripts/setup.sh
# Select option 2 in the menu
🤖 Agent Only Installation
Connect to external Manager
# Interactive mode
sudo ./scripts/setup.sh
# Select option 3 in the menu
# Pre-authorized mode
sudo ./scripts/setup.sh --agent-only --manager-url https://manager.company.com:8443 --pre-token xyz789
🔧 Development Setup
Development environment with build tools
sudo ./scripts/setup.sh
# Select option 4 in the menu
Setup Script Features
Automated Features:
- • System dependency detection and installation
- • PostgreSQL database setup and configuration
- • Go programming language installation
- • Project compilation and building
- • Systemd service creation and configuration
- • TLS certificate generation (Let's Encrypt or self-signed)
- • Authentication setup and admin user creation
- • Network interface detection and configuration
- • Production fixes application
eBPF Activation Script (enable-ebpf.sh)
The enable-ebpf.sh script activates full eBPF protection with all security features.
# Enable eBPF protection
sudo ./scripts/enable-ebpf.sh
# This script performs:
# 1. Applies production fixes to source code
# 2. Rebuilds services with fixes
# 3. Compiles eBPF programs with all features
# 4. Updates agent configuration
# 5. Restarts services with eBPF enabled
# 6. Verifies eBPF activation
eBPF Activation Process:
- • Stops existing services safely
- • Cleans up old eBPF programs and maps
- • Compiles production-ready eBPF programs
- • Loads programs onto network interfaces
- • Verifies protection is active
- • Provides real-time status monitoring
Management and Rebuild Scripts
Manager Rebuild (rebuild-manager.sh)
Rebuilds the Manager service after configuration changes or code updates.
# Rebuild manager with latest changes
sudo ./scripts/rebuild-manager.sh
# Features:
# - Stops manager service safely
# - Rebuilds from latest source code
# - Copies updated web files
# - Applies database fixes
# - Restarts service with new binary
# - Tests API endpoints automatically
# - Supports both HTTP and HTTPS configurations
Agent Rebuild (rebuild-agent-only.sh)
Rebuilds the Agent service with updated configuration and eBPF programs.
# Interactive agent rebuild
sudo ./scripts/rebuild-agent-only.sh
# Features:
# - Interactive configuration prompts
# - Manager connectivity testing
# - Network interface selection
# - Pre-registration token support
# - Automatic service restart
# - Registration verification
# - Detailed logging and troubleshooting
System Status (system-status.sh)
Comprehensive system health check and status monitoring.
# Check complete system status
sudo ./scripts/system-status.sh
# Features:
# - Service status (Manager, Agent, Database)
# - Network connectivity verification
# - eBPF program status and loading verification
# - Configuration file validation
# - API connectivity testing
# - Recent activity logs
# - Health score calculation
# - Automated recommendations
eBPF Monitoring (ebpf_monitor.sh)
Real-time monitoring of eBPF programs and firewall activity.
# Real-time dashboard
sudo ./scripts/ebpf_monitor.sh dashboard
# Other commands:
sudo ./scripts/ebpf_monitor.sh status # Current status
sudo ./scripts/ebpf_monitor.sh monitor # Event monitoring
sudo ./scripts/ebpf_monitor.sh stats # Detailed statistics
sudo ./scripts/ebpf_monitor.sh programs # eBPF programs list
sudo ./scripts/ebpf_monitor.sh maps # eBPF maps list
sudo ./scripts/ebpf_monitor.sh report # Performance report
eBPF Testing (test_ebpf.sh)
Comprehensive testing of eBPF firewall functionality.
# Run full eBPF test suite
sudo ./scripts/test_ebpf.sh
# Test specific interface
sudo ./scripts/test_ebpf.sh -i eth0 -d 60
# Compile only (no testing)
sudo ./scripts/test_ebpf.sh --compile-only
# Features:
# - BPDU blocking tests
# - MAC spoofing detection tests
# - Port scanning simulation
# - Performance verification
# - Result analysis and reporting
Manager Setup
Configuration
The Manager requires configuration for database connection, server settings, and security parameters.
# Example manager configuration (config/manager.yaml)
database:
host: localhost
port: 5432
database: zwall
username: zwall
password: secure_password
sslmode: require
server:
host: 0.0.0.0
port: 8080
tls_cert: /etc/zwall/certs/server.crt
tls_key: /etc/zwall/certs/server.key
security:
jwt_secret: your-jwt-secret-key
session_timeout: 24h
max_request_size: 10MB
logging:
level: info
format: json
output: /var/log/zwall/manager.log
Service Management
# Start the Manager service
sudo systemctl enable zwall-manager
sudo systemctl start zwall-manager
# Check service status
sudo systemctl status zwall-manager
# View logs
sudo journalctl -u zwall-manager -f
Default Access: After installation, access the web interface at https://localhost:8080
(default credentials: admin/admin - change immediately after first login)
Agent Setup
Agent Registration
Agents must be pre-registered with the Manager before deployment for secure authentication.
# 1. Pre-register agent via web interface
# Navigate to: Agents → Pre-register → Add New Agent
# Generate token and note the agent ID
# 2. Configure agent
sudo mkdir -p /etc/zwall
sudo tee /etc/zwall/agent.yaml > /dev/null <
Verification
# Check agent status
sudo systemctl status zwall-agent
# Verify eBPF programs loaded
sudo bpftool prog list | grep zwall
# Check agent logs
sudo journalctl -u zwall-agent -f
# Verify manager connection
curl -k https://manager-ip:8080/api/v1/agents/status
Security Note: Always use TLS certificates in production and rotate agent tokens regularly.
Firewall Components
eBPF/XDP Engine
Kernel-level packet processing with sub-microsecond latency
- • XDP ingress filtering at driver level
- • Zero-copy packet processing
- • 14.88 Mpps processing rate
- • Minimal CPU overhead (<5%)
Traffic Control (TC)
Egress filtering and traffic shaping
- • Outbound packet filtering
- • Bandwidth rate limiting
- • QoS policy enforcement
- • Traffic prioritization
Rule Engine
Flexible policy evaluation system
- • IPv4/IPv6 address filtering
- • TCP/UDP port control
- • MAC address policies
- • Protocol-specific rules
Security Features
Advanced threat detection and mitigation
- • BPDU attack prevention
- • Rate limiting and DDoS protection
- • Port scan detection
- • Behavioral analysis
eBPF Program Structure
// Main eBPF firewall program structure
struct {
__uint(type, BPF_MAP_TYPE_HASH);
__uint(max_entries, 100000);
__type(key, struct ip_key);
__type(value, struct rule_action);
} ip_rules SEC(".maps");
struct {
__uint(type, BPF_MAP_TYPE_HASH);
__uint(max_entries, 10000);
__type(key, struct port_key);
__type(value, struct rule_action);
} port_rules SEC(".maps");
SEC("xdp")
int xdp_firewall(struct xdp_md *ctx) {
// Parse packet headers
// Check IP rules
// Check port rules
// Apply action (PASS/DROP)
return action;
}
eBPF Technical Documentation
Core eBPF Programs
firewall.c (XDP Ingress)
Main firewall program for ingress traffic filtering
// Key Features:
// - BPDU attack detection and blocking
// - MAC spoofing prevention
// - Port scanning detection
// - IP and port filtering
// - Protocol-based blocking
// - Rate limiting and DDoS protection
// - VM network isolation
// - Broadcast traffic control
// - DHCP server authorization
firewall_egress.c (TC Egress)
Egress traffic filtering and broadcast control
// Key Features:
// - Outbound broadcast blocking
// - Egress IP filtering
// - Port scan detection for outbound traffic
// - Traffic Control (TC) integration
// - Interface-specific policies
firewall_simple.c
Minimal firewall for basic protection
// Key Features:
// - Basic packet counting
// - Simple MAC filtering
// - Minimal resource usage
// - Easy debugging and testing
eBPF Maps Structure
// Statistics Map (PERCPU_ARRAY)
struct stats {
__u64 total_packets;
__u64 blocked_bpdu;
__u64 blocked_mac_spoof;
__u64 blocked_port_scan;
__u64 allowed_packets;
__u64 blocked_ips;
__u64 blocked_ports;
__u64 blocked_protocols;
__u64 blocked_syn_flood;
__u64 blocked_icmp_flood;
__u64 blocked_dhcp;
__u64 rate_limited;
__u64 total_blocked;
__u64 blocked_broadcast;
__u64 blocked_vm_isolation;
__u64 blocked_dhcp_unauthorized;
__u64 blocked_outbound_ports;
__u64 whitelist_allowed;
__u64 vm_traffic_processed;
};
// Blocked IPs (HASH)
struct {
__uint(type, BPF_MAP_TYPE_HASH);
__uint(max_entries, MAX_ENTRIES);
__type(key, __u32); // IP address
__type(value, __u64); // Blocked until timestamp
} blocked_ips SEC(".maps");
// Port Scan Tracker (LRU_HASH)
struct port_scan_info {
__u64 last_seen;
__u32 port_count;
__u32 blocked_until;
};
struct {
__uint(type, BPF_MAP_TYPE_LRU_HASH);
__uint(max_entries, 1000);
__type(key, __u32); // Source IP
__type(value, struct port_scan_info);
} port_scan_tracker SEC(".maps");
// MAC Address Control (HASH)
struct {
__uint(type, BPF_MAP_TYPE_HASH);
__uint(max_entries, MAX_ENTRIES);
__type(key, __u8[6]); // MAC address
__type(value, __u32); // Interface index
} blocked_macs SEC(".maps");
struct {
__uint(type, BPF_MAP_TYPE_HASH);
__uint(max_entries, MAX_ENTRIES);
__type(key, __u32); // Interface index
__type(value, __u8[6]); // Allowed MAC address
} allowed_macs SEC(".maps");
Security Event Types
Layer 2 Threats
- • EVENT_BPDU_BLOCKED (1)
- • EVENT_MAC_SPOOF (2)
- • EVENT_BROADCAST_BLOCKED (11)
Network Scanning
- • EVENT_PORT_SCAN (3)
- • EVENT_PORT_SCAN_OUTBOUND (106)
IP/Port Filtering
- • EVENT_IP_BLOCKED (4)
- • EVENT_PORT_BLOCKED (5)
- • EVENT_PROTOCOL_BLOCKED (6)
DDoS Protection
- • EVENT_SYN_FLOOD (7)
- • EVENT_ICMP_FLOOD (8)
- • EVENT_RATE_LIMIT_EXCEEDED (10)
DHCP Security
- • EVENT_DHCP_BLOCKED (9)
- • EVENT_DHCP_UNAUTHORIZED (13)
VM Security
- • EVENT_VM_ISOLATION (12)
- • EVENT_VM_TRAFFIC_DETECTED (17)
eBPF Program Compilation
# Compile eBPF programs
cd ebpf/
make clean
make
# Compilation process:
# 1. C source files (.c) compiled to LLVM IR
# 2. LLVM IR optimized and converted to BPF bytecode
# 3. BPF bytecode embedded in ELF object file (.o)
# 4. Object file loaded by Go agent using cilium/ebpf
# Compiler flags:
# -O2: Optimization level 2
# -target bpf: Target BPF architecture
# -c: Compile only (no linking)
# -g: Include debug information for BTF
# Example compilation:
clang -O2 -target bpf -c firewall.c -o firewall.o -g
Performance Characteristics
eBPF Performance Metrics:
- • Latency: Sub-microsecond packet processing
- • Throughput: 14.88 million packets per second (Mpps)
- • CPU Overhead: Less than 5% for full protection
- • Memory Usage: ~2-4MB per interface
- • Map Lookups: O(1) hash table operations
- • Event Rate: Up to 1000 events/second sustained
- • Zero Copy: Direct NIC to userspace data transfer
eBPF Program Loading Process
// Go code for loading eBPF program
func loadEBPFProgram() error {
// 1. Open ELF object file
spec, err := ebpf.LoadCollectionSpec("ebpf/firewall.o")
if err != nil {
return fmt.Errorf("failed to load eBPF spec: %v", err)
}
// 2. Create collection from spec
coll, err := ebpf.NewCollection(spec)
if err != nil {
return fmt.Errorf("failed to create collection: %v", err)
}
// 3. Get XDP program
prog := coll.Programs["firewall_prog"]
if prog == nil {
return fmt.Errorf("firewall_prog not found in eBPF object")
}
// 4. Attach to network interface
link, err := netlink.LinkByName("eth0")
if err != nil {
return fmt.Errorf("failed to get interface: %v", err)
}
// 5. Attach XDP program
err = netlink.LinkSetXdpFd(link, prog.FD())
if err != nil {
return fmt.Errorf("failed to attach XDP program: %v", err)
}
return nil
}
Installation Guide
Automated Installation with setup.sh
Prerequisites:
- • Linux distribution (Ubuntu 18.04+, CentOS 7+, AlmaLinux 8+)
- • Root or sudo privileges
- • Internet connection for package downloads
- • At least 2GB RAM, 10GB disk space
- • Go 1.19+ (will be installed if missing)
- • PostgreSQL 12+ (will be installed if missing)
Deployment Modes
Full System Installation
Complete firewall system with manager and agent
# Interactive mode
sudo ./scripts/setup.sh
# Non-interactive mode
sudo ./scripts/setup.sh --mode full --auto
Installs: PostgreSQL, Go, Manager, Agent, eBPF programs, Web UI
Core Only Installation
Manager and database only (no agent)
# Interactive mode
sudo ./scripts/setup.sh --mode core
# Non-interactive mode
sudo ./scripts/setup.sh --mode core --auto
Installs: PostgreSQL, Go, Manager, Web UI
Agent Only Installation
Agent component only (requires existing manager)
# Interactive mode
sudo ./scripts/setup.sh --mode agent
# Non-interactive mode
sudo ./scripts/setup.sh --mode agent --auto
Installs: Go, Agent, eBPF programs
Development Installation
Development environment with all components
# Interactive mode
sudo ./scripts/setup.sh --mode dev
# Non-interactive mode
sudo ./scripts/setup.sh --mode dev --auto
Installs: All components with debug options
Installation Process
# 1. Download and extract the project
wget https://github.com/your-org/firewall-project/archive/main.zip
unzip main.zip
cd firewall-project-main
# 2. Make scripts executable
chmod +x scripts/*.sh
# 3. Run setup script
sudo ./scripts/setup.sh
# 4. Follow interactive prompts:
# - Select deployment mode
# - Configure database settings
# - Set manager IP/hostname
# - Configure TLS certificates
# - Set up authentication tokens
Configuration Files Created
Manager Configuration
/etc/firewall-manager/config.yaml
# Database settings
# API endpoints
# TLS certificates
# Authentication settings
Agent Configuration
/etc/firewall-agent/config.yaml
# Manager connection
# Interface settings
# eBPF program paths
# Logging configuration
Systemd Services
/etc/systemd/system/firewall-manager.service
/etc/systemd/system/firewall-agent.service
# Auto-start configuration
# Security settings
# Resource limits
Database Setup
# PostgreSQL database created
# Tables and indexes initialized
# Default admin user created
# Connection pooling configured
Post-Installation Steps
# 1. Verify services are running
sudo systemctl status firewall-manager
sudo systemctl status firewall-agent
# 2. Check eBPF programs are loaded
sudo bpftool prog list | grep firewall
# 3. Test connectivity
curl -k https://localhost:8443/api/health
# 4. Access web interface
# Open https://your-server:8443 in browser
# Default credentials: admin / setup-generated-password
# 5. Enable eBPF protection (if not auto-enabled)
sudo ./scripts/enable-ebpf.sh
Troubleshooting Installation
Common Issues:
- • Permission denied: Run with sudo or as root
- • Package installation fails: Check internet connection and package manager
- • Go compilation fails: Ensure Go 1.19+ is installed correctly
- • Database connection fails: Verify PostgreSQL is running and accessible
- • eBPF loading fails: Check kernel version (4.18+) and BTF support
# Check system requirements
./scripts/setup.sh --check-only
# View detailed logs
sudo journalctl -u firewall-manager -f
sudo journalctl -u firewall-agent -f
# Re-run setup with verbose output
sudo ./scripts/setup.sh --verbose
Web Panel Usage
Dashboard Overview
The main dashboard provides real-time visibility into system health, security events, and network traffic.
Firewall Rules Management
Comprehensive rule management interface with drag-and-drop configuration.
Rule Creation
Intuitive rule builder with validation and testing capabilities.
Rule Types
Support for various rule types including IP, port, and protocol filtering.
Agent Management
Monitor and control all deployed agents from a centralized interface.
Agent Monitoring
Real-time agent health monitoring and performance metrics.
Pre-registration
Secure agent registration system with token-based authentication.
Database Schema & Usage
Core Tables
Rules Table
CREATE TABLE rules (
id SERIAL PRIMARY KEY,
rule_type VARCHAR(50) NOT NULL,
parameters JSONB NOT NULL,
priority INTEGER DEFAULT 1,
scope VARCHAR(20) DEFAULT 'global',
is_enabled BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Agents Table
CREATE TABLE agents (
id SERIAL PRIMARY KEY,
hostname VARCHAR(255) NOT NULL,
ip_address VARCHAR(45) NOT NULL,
status VARCHAR(20) DEFAULT 'offline',
last_heartbeat TIMESTAMP,
token VARCHAR(1000) NOT NULL,
ebpf_loaded BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
Security Logs Table
CREATE TABLE security_logs (
id BIGSERIAL PRIMARY KEY,
agent_id INTEGER REFERENCES agents(id),
rule_id INTEGER REFERENCES rules(id),
log_type VARCHAR(50) NOT NULL,
source_ip VARCHAR(45),
destination_ip VARCHAR(45),
action VARCHAR(20) NOT NULL,
severity VARCHAR(20) DEFAULT 'low',
created_at TIMESTAMP DEFAULT NOW()
);
Agent Rules Table
CREATE TABLE agent_rules (
agent_id INTEGER REFERENCES agents(id),
rule_id INTEGER REFERENCES rules(id),
assigned_at TIMESTAMP DEFAULT NOW(),
PRIMARY KEY (agent_id, rule_id)
);
Database Operations
// Rule creation example
INSERT INTO rules (rule_type, parameters, priority, scope)
VALUES ('BLOCK_IP', '{"source_ip": "192.168.1.100"}', 1, 'global');
// Agent registration
INSERT INTO agents (hostname, ip_address, token)
VALUES ('server-01', '192.168.1.10', 'generated-token');
// Security event logging
INSERT INTO security_logs (agent_id, rule_id, source_ip, action, severity)
VALUES (1, 1, '10.0.0.5', 'blocked', 'medium');
Indexing Strategy: The database uses strategic indexing on frequently queried columns (agent_id, rule_id, created_at, source_ip) for optimal performance with large datasets.
System Workflow
Rule Lifecycle
- Rule Creation: Administrator creates firewall rule via web interface
- Validation: Manager validates rule parameters and syntax
- Storage: Rule stored in database with metadata
- Distribution: Rule synchronized to relevant agents
- Application: Agent loads rule into eBPF maps
- Enforcement: eBPF program applies rule to network packets
- Monitoring: Security events logged and forwarded to manager
- Reporting: Events displayed in web interface and stored for analysis
Packet Processing Flow
1
Packet Arrival: Network packet reaches network interface
2
XDP Hook: eBPF program intercepts packet at driver level
3
Header Parsing: Extract IP, port, protocol information
4
Rule Matching: Check packet against eBPF maps
5
Action Decision: PASS, DROP, or REDIRECT
6
Event Logging: Security events sent to userspace agent
Agent Synchronization
// Agent sync process (runs every 30 seconds)
func (a *Agent) syncRules() error {
// 1. Request rules from manager
resp, err := http.Get(fmt.Sprintf("%s/api/v1/agents/sync-rules", a.managerURL))
if err != nil {
return err
}
// 2. Parse rule updates
var rules []Rule
if err := json.NewDecoder(resp.Body).Decode(&rules); err != nil {
return err
}
// 3. Apply rules to eBPF maps
for _, rule := range rules {
if err := a.applyRule(rule); err != nil {
log.Printf("Failed to apply rule %d: %v", rule.ID, err)
}
}
return nil
}
API Reference
Authentication
# JWT Token Authentication
curl -H "Authorization: Bearer your-jwt-token" \
-H "Content-Type: application/json" \
https://manager:8443/api/v1/rules
# Login to get JWT token
curl -X POST https://manager:8443/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"your-password"}'
# Response:
# {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","expires_at":"2024-12-31T23:59:59Z"}
Firewall Rules API
GET /api/v1/rules
List all firewall rules with filtering options
# List all rules
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/rules
# Filter by status
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/rules?status=enabled"
# Filter by type
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/rules?type=BLOCK_IP"
# Paginated results
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/rules?page=1&limit=50"
POST /api/v1/rules
Create a new firewall rule
# Block IP address
curl -X POST -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"rule_type": "BLOCK_IP",
"parameters": {"source_ip": "192.168.1.100"},
"priority": 1,
"scope": "global",
"description": "Block suspicious IP"
}' \
https://manager:8443/api/v1/rules
# Block port
curl -X POST -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"rule_type": "BLOCK_PORT",
"parameters": {"port": 22, "protocol": "tcp"},
"priority": 2,
"scope": "global"
}' \
https://manager:8443/api/v1/rules
PUT /api/v1/rules/{id}
Update an existing rule
# Update rule status
curl -X PUT -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{"is_enabled": false}' \
https://manager:8443/api/v1/rules/123
# Update rule parameters
curl -X PUT -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"parameters": {"source_ip": "192.168.1.200"},
"description": "Updated IP block"
}' \
https://manager:8443/api/v1/rules/123
DELETE /api/v1/rules/{id}
Delete a firewall rule
curl -X DELETE -H "Authorization: Bearer token" \
https://manager:8443/api/v1/rules/123
# Response: {"message": "Rule deleted successfully"}
Agent Management API
GET /api/v1/agents
List all registered agents
# List all agents
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/agents
# Filter by status
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/agents?status=online"
# Get agent details
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/agents/123
POST /api/v1/agents/register
Register a new agent
curl -X POST -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"hostname": "server-01",
"ip_address": "192.168.1.10",
"description": "Web server agent"
}' \
https://manager:8443/api/v1/agents/register
# Response: {"agent_id": 123, "token": "abc123xyz..."}
GET /api/v1/agents/{id}/status
Get agent health status
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/agents/123/status
# Response:
# {
# "agent_id": 123,
# "status": "online",
# "last_heartbeat": "2024-01-15T10:30:00Z",
# "ebpf_loaded": true,
# "interfaces": ["eth0", "eth1"],
# "rules_count": 25
# }
POST /api/v1/agents/deploy
Deploy rules to specific agents
# Deploy to single agent
curl -X POST -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{"agent_ids": [123]}' \
https://manager:8443/api/v1/agents/deploy
# Deploy to multiple agents
curl -X POST -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{"agent_ids": [123, 124, 125]}' \
https://manager:8443/api/v1/agents/deploy
Security Events API
GET /api/v1/events
Retrieve security events
# Get recent events
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/events
# Filter by severity
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/events?severity=high"
# Filter by agent
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/events?agent_id=123"
# Time range filter
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/events?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z"
GET /api/v1/events/stats
Get event statistics
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/events/stats
# Response:
# {
# "total_events": 15420,
# "events_today": 234,
# "by_severity": {
# "low": 12000,
# "medium": 3200,
# "high": 220
# },
# "by_type": {
# "BLOCKED_IP": 8900,
# "PORT_SCAN": 4500,
# "DDoS_ATTACK": 2020
# }
# }
POST /api/v1/events/export
Export events to CSV
curl -X POST -H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"format": "csv",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-31T23:59:59Z",
"filters": {"severity": "high"}
}' \
https://manager:8443/api/v1/events/export
System Management API
GET /api/v1/health
System health check
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/health
# Response:
# {
# "status": "healthy",
# "database": "connected",
# "services": ["manager", "agent"],
# "uptime": "7d 4h 23m",
# "version": "1.0.0"
# }
GET /api/v1/config
Get system configuration
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/config
# Response: Current system configuration
POST /api/v1/config/reload
Reload system configuration
curl -X POST -H "Authorization: Bearer token" \
https://manager:8443/api/v1/config/reload
# Response: {"message": "Configuration reloaded successfully"}
GET /api/v1/logs
Retrieve system logs
# Get recent logs
curl -H "Authorization: Bearer token" \
https://manager:8443/api/v1/logs
# Filter by level
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/logs?level=error"
# Get logs for specific service
curl -H "Authorization: Bearer token" \
"https://manager:8443/api/v1/logs?service=agent"
Configuration Files
Manager Configuration
# /etc/firewall-manager/config.yaml
database:
host: localhost
port: 5432
database: firewall
username: firewall
password: secure_password
sslmode: require
max_connections: 100
server:
host: 0.0.0.0
port: 8443
tls_cert: /etc/firewall/certs/server.crt
tls_key: /etc/firewall/certs/server.key
read_timeout: 30s
write_timeout: 30s
security:
jwt_secret: your-256-bit-secret-key
session_timeout: 24h
max_request_size: 10MB
bcrypt_cost: 12
logging:
level: info
format: json
output: /var/log/firewall/manager.log
max_size: 100MB
max_backups: 5
Agent Configuration
# /etc/firewall-agent/config.yaml
manager:
host: manager.example.com
port: 8443
token: agent-registration-token
tls_skip_verify: false
reconnect_interval: 30s
heartbeat_interval: 60s
agent:
id: pre-registered-agent-id
hostname: server-01
interfaces: [eth0, eth1, wlan0]
log_level: info
buffer_size: 1000
ebpf:
maps_max_entries: 100000
programs_path: /usr/lib/firewall/ebpf
stats_interval: 60s
event_batch_size: 100
logging:
level: info
format: json
output: /var/log/firewall/agent.log
max_size: 50MB
max_backups: 3
Error Codes
Common API Error Responses:
- 400 Bad Request: Invalid request parameters or malformed JSON
- 401 Unauthorized: Missing or invalid authentication token
- 403 Forbidden: Insufficient permissions for the operation
- 404 Not Found: Resource or endpoint does not exist
- 409 Conflict: Resource already exists or state conflict
- 422 Unprocessable Entity: Validation errors in request data
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server-side processing error
- 503 Service Unavailable: Service temporarily unavailable
Rate Limiting
# Rate limits by endpoint:
# - Authentication: 10 requests/minute
# - Rules management: 100 requests/minute
# - Agent operations: 200 requests/minute
# - Events querying: 500 requests/minute
# - Health checks: Unlimited
# Rate limit headers in response:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1640995200
# Rate limit exceeded response:
# HTTP 429 Too Many Requests
# {"error": "Rate limit exceeded", "retry_after": 60}
Monitoring & Security Events
Security Logs
Comprehensive security event logging with real-time streaming and historical analysis.
Blocked IPs Management
Monitor and manage blocked IP addresses with automatic threat intelligence integration.
Network Isolation
DHCP service control for network access management.
Broadcast Control
Broadcast traffic management to prevent network storms.
Port Scan Detection
Advanced port scanning detection with whitelist support.
Manager Logs
Comprehensive manager activity logging and audit trails.
Agent Shell Access
Secure remote shell access to agents for advanced troubleshooting and maintenance.
Settings Panel
System configuration and settings management interface.
Troubleshooting
System Status Monitoring
system-status.sh - Comprehensive System Health Check:
- • Service status verification (Manager, Agent, Database)
- • Network connectivity testing
- • eBPF program loading verification
- • Configuration file validation
- • API endpoint testing
- • Recent activity logs analysis
- • Health score calculation
- • Automated recommendations
# Run complete system status check
sudo ./scripts/system-status.sh
# Check specific components
sudo ./scripts/system-status.sh --services # Service status only
sudo ./scripts/system-status.sh --network # Network connectivity
sudo ./scripts/system-status.sh --ebpf # eBPF verification
sudo ./scripts/system-status.sh --config # Configuration validation
# Generate status report
sudo ./scripts/system-status.sh --report > status_report.txt
eBPF Monitoring and Diagnostics
ebpf_monitor.sh Commands
# Real-time dashboard
sudo ./scripts/ebpf_monitor.sh dashboard
# Current status
sudo ./scripts/ebpf_monitor.sh status
# Event monitoring
sudo ./scripts/ebpf_monitor.sh monitor
# Performance statistics
sudo ./scripts/ebpf_monitor.sh stats
# eBPF programs list
sudo ./scripts/ebpf_monitor.sh programs
# eBPF maps list
sudo ./scripts/ebpf_monitor.sh maps
# Performance report
sudo ./scripts/ebpf_monitor.sh report
test_ebpf.sh Testing
# Full eBPF test suite
sudo ./scripts/test_ebpf.sh
# Test specific interface
sudo ./scripts/test_ebpf.sh -i eth0 -d 60
# Compile only (no testing)
sudo ./scripts/test_ebpf.sh --compile-only
# Test BPDU blocking
sudo ./scripts/test_ebpf.sh --test-bpdu
# Test port scanning detection
sudo ./scripts/test_ebpf.sh --test-portscan
Common Issues
eBPF Program Loading Failed
# Check kernel version
uname -r
# Verify eBPF support
ls /sys/fs/bpf/
# Check dmesg for errors
dmesg | grep bpf
# Rebuild eBPF programs
cd ebpf/
make clean && make
# Test eBPF loading
sudo ./scripts/test_ebpf.sh --compile-only
# Check BTF support
sudo bpftool btf list
Agent Connection Failed
# Check network connectivity
ping manager-host
# Verify TLS certificates
openssl s_client -connect manager-host:8443
# Check agent logs
sudo journalctl -u firewall-agent -f
# Validate configuration
sudo cat /etc/firewall-agent/config.yaml
# Test API connectivity
curl -k https://manager:8443/api/v1/health
# Check agent registration
sudo ./scripts/system-status.sh --network
Database Connection Issues
# Test database connection
psql -h localhost -U firewall -d firewall
# Check PostgreSQL service
sudo systemctl status postgresql
# Verify connection string
sudo cat /etc/firewall-manager/config.yaml
# Check database logs
sudo tail -f /var/log/postgresql/postgresql-*.log
# Test with pg_isready
pg_isready -h localhost -p 5432 -U firewall
High CPU Usage
# Monitor eBPF program performance
sudo ./scripts/ebpf_monitor.sh stats
# Check system resources
top -p $(pgrep firewall)
# Analyze network traffic
sudo nload
# Review eBPF map sizes
sudo bpftool map list
# Check for eBPF program leaks
sudo bpftool prog list | wc -l
# Monitor event rates
sudo ./scripts/ebpf_monitor.sh monitor
Service Startup Issues
# Check service status
sudo systemctl status firewall-manager
sudo systemctl status firewall-agent
# View service logs
sudo journalctl -u firewall-manager -n 50
sudo journalctl -u firewall-agent -n 50
# Restart services
sudo systemctl restart firewall-manager
sudo systemctl restart firewall-agent
# Check configuration syntax
sudo firewall-manager --config-check
sudo firewall-agent --config-check
Network Interface Issues
# List network interfaces
ip link show
# Check interface capabilities
ethtool -k eth0 | grep xdpgeneric
# Verify XDP support
ip link show eth0
# Check eBPF attachment
sudo bpftool net list
# Test interface with eBPF
sudo ./scripts/test_ebpf.sh -i eth0
Performance Tuning
Optimization Tips:
- • Increase eBPF map sizes for high-traffic environments
- • Use connection pooling for database operations
- • Implement log rotation to prevent disk space issues
- • Configure appropriate rate limiting thresholds
- • Monitor memory usage and adjust cache sizes
- • Use multiple CPU cores for parallel processing
- • Optimize eBPF program complexity for better performance
Log Analysis
# View manager logs
sudo journalctl -u firewall-manager -f
# View agent logs
sudo journalctl -u firewall-agent -f
# Search for specific errors
sudo journalctl -u firewall-manager | grep ERROR
# Export logs for analysis
sudo journalctl -u firewall-manager --since "2024-01-01" > manager_logs.txt
# Monitor real-time events
sudo ./scripts/ebpf_monitor.sh monitor
# Check security event logs
sudo tail -f /var/log/firewall/security.log
Rebuild and Recovery Procedures
Manager Rebuild
# Rebuild manager after code changes
sudo ./scripts/rebuild-manager.sh
# Features:
# - Safe service stop
# - Code rebuild with latest changes
# - Web files update
# - Database fixes application
# - Service restart with verification
Agent Rebuild
# Rebuild agent with new configuration
sudo ./scripts/rebuild-agent-only.sh
# Features:
# - Interactive configuration
# - Manager connectivity testing
# - Network interface selection
# - Pre-registration token support
# - Automatic service restart
eBPF Rebuild
# Rebuild eBPF programs
sudo ./scripts/enable-ebpf.sh
# Features:
# - Production fixes application
# - eBPF compilation with BTF
# - Service restart
# - Protection verification
# - Status reporting
Emergency Procedures
Critical Failure Recovery:
- • Stop all services:
sudo systemctl stop firewall-manager firewall-agent - • Unload eBPF programs:
sudo ip link set dev eth0 xdpgeneric off - • Clear eBPF maps:
sudo rm -rf /sys/fs/bpf/* - • Reset database:
sudo ./scripts/setup.sh --reset-db - • Clean rebuild:
sudo ./scripts/setup.sh --clean-install