██████╗ █████╗ █████╗ ███╗ ██╗
██╔════╝██╔══██╗██╔══██╗████╗ ██║
██║ ███████║███████║██╔██╗ ██║
██║ ██╔══██║██╔══██║██║╚██╗██║
╚██████╗██║ ██║██║ ██║██║ ╚████║
╚═════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝
System Tools for Configuration and Automation of Advanced Networking
Professional infrastructure toolkit for enterprise Linux network management
Features • Quick Start • Tools • Documentation • Contributing • Community
CAAN System Tools is a comprehensive, open-source toolkit for advanced Linux network configuration and automation. Born from enterprise consulting experience, CAAN provides intelligent, safe, and auditable workflows for complex network infrastructure tasks that traditionally require deep networking expertise.
- Safety First: Dry-run by default, automatic backups, one-command rollback
- Intelligence: Hardware-aware recommendations, validation at every step
- Transparency: Complete audit trails, detailed logging, plan-before-execute
- Accessibility: CLI, GUI, and TUI modes for every environment
- Community: Open-source, welcoming contributions, comprehensive documentation
Modern data centers and enterprise infrastructure demand:
- High Availability: Link aggregation with automatic failover
- Performance: Load balancing across multiple network links
- Complexity Management: VLANs, dual-stack IPv4/IPv6, SDN topologies
- Safety: Changes must be reversible, testable, and auditable
- Automation: Scriptable workflows for Infrastructure-as-Code
CAAN transforms these challenges from error-prone manual configurations into guided, tested, production-ready workflows.
NetworkManager-based bonding and VLAN configuration wizard
Current Version: v0.4.5 (February 2026)
Key Features
- 802.3ad (LACP) - IEEE standard link aggregation with switch support
- active-backup - Primary/failover configuration for high availability
- balance-xor - Transmit load balancing based on source/destination
- balance-tlb - Adaptive transmit load balancing
- balance-alb - Adaptive load balancing (transmit and receive)
- CLI Mode - Command-line for automation and scripts
- Zenity GUI - Graphical interface for desktop environments
- TUI Mode - ncurses terminal UI using dialog/whiptail
- VLAN Support - Multiple tagged VLANs per bond with independent IP configuration
- Dual-Stack Networking - IPv4-only, IPv6-only, or simultaneous dual-stack
- Flexible Addressing - DHCP, static IPs, IPv6 SLAAC/DHCPv6, ULA addressing
- Dry-Run by Default - Shows planned changes without applying them
- Automatic Backups - Timestamped NetworkManager configuration backups
- One-Command Rollback - Instant recovery from configuration issues
- Input Validation - Multi-layer validation prevents invalid configurations
- Comprehensive Logging - Full audit trail with timestamps
- Hardware Detection - Automatic discovery of network interfaces
- Capability Analysis - Reports link speeds, duplex, vendor information
- Mode Recommendations - Suggests optimal bond mode based on hardware
- Interface Validation - Ensures interfaces are available and compatible
Quick Start:
# Interactive wizard (dry-run)
sudo ./bonding-wizrd/nm-bond-wizard-0.4.5.sh
# Create bond with confirmation
sudo ./bonding-wizrd/nm-bond-wizard-0.4.5.sh --apply
# Command-line mode
sudo ./bonding-wizrd/nm-bond-wizard-0.4.5.sh \
-i enp1s0,enp2s0 -b bond0 --mode active-backup --applyOpen vSwitch configuration wizard for software-defined networking
Current Version: v0.2.0 (February 2026)
Key Features
- Bridge Management - Create, configure, and manage OVS bridges
- Port Configuration - Physical ports, internal ports, patch ports
- Bond Support - LACP, balance-slb, balance-tcp bonding modes
- VLAN Management - Access ports, trunk ports, VLAN filtering
- Tunnel Interfaces - GRE, VXLAN, Geneve support (coming soon)
- QoS Configuration - Rate limiting, traffic shaping
- Port Mirroring - SPAN, RSPAN, ERSPAN (planned)
- OpenFlow - Controller integration (planned)
- Dry-Run Mode - Preview all changes before applying
- Configuration Backup - Automatic snapshots with rollback
- Validation - Multi-layer validation of all inputs
- Audit Trail - Complete logging of all operations
- Multi-UI Support - CLI, GUI (Zenity), TUI (dialog)
- Hardware Detection - Automatic interface discovery
- Template System - Pre-built configuration templates
- Interactive Prompts - Guided configuration workflows
Quick Start:
# Interactive wizard (dry-run)
sudo ./ovs-wizrd/ovs-wizard-0.2.0.sh
# Create bridge with ports
sudo ./ovs-wizrd/ovs-wizard-0.2.0.sh \
--bridge br0 --ports eth0,eth1 --applyFlask-based web UI for centralized network management
Status: Active Development
Planned Features
- Real-time network status monitoring
- Interface health and statistics
- Bond/bridge configuration overview
- Alert and notification system
- Web-based wizard workflows
- Template library and deployment
- Bulk operations across multiple nodes
- Configuration versioning and rollback
- Centralized management of multiple servers
- Remote agent communication (SSH/API)
- Distributed configuration deployment
- Topology visualization
- Role-based access control (RBAC)
- Audit logging and compliance
- API authentication and authorization
- Secure credential management
Multi-layer input validation for network configurations
Status: v1.0.0 (Stable)
Validation Layers
- Character set validation (alphanumeric, hyphens, underscores)
- Length constraints
- Format verification
- IPv4/IPv6 address format and range checking
- VLAN ID range validation (1-4094)
- MAC address format validation
- Network prefix validation
- Interface existence and availability
- NetworkManager/OVS service status
- Kernel module availability
- Permission and capability checks
- Bond mode compatibility
- VLAN conflict detection
- IP address uniqueness
- Interface already-configured checks
- Interface capability detection
- Link state verification
- Speed/duplex compatibility
- Driver and firmware checks
Usage:
# Standalone validation
source lib/validation_lib.sh
validate_ipv4 "192.168.1.100"
validate_interface_available "eth0"
validate_vlan_id 100Automated testing infrastructure with Podman and Open vSwitch
Lab Features
- Single-node lab - Basic NetworkManager testing
- Multi-node lab - Complex topologies with OVS
- Portable lab - Reproducible environment via containers
- CI/CD integration - Automated testing in GitHub Actions
- Fast deployment - 30-60 seconds to full lab
- Quick reset - 5 seconds to clean slate
- Isolated testing - No impact on host networking
- Hardware simulation - Multiple interfaces via veth pairs
- LACP testing - OVS configured as LACP-capable switch
# Deploy lab
sudo lab/setup-bond-ovs-lab-v2.sh
# Enter lab container
sudo lab/enter-lab.sh
# Reset to clean state
sudo lab/reset-lab.sh --force
# Teardown completely
sudo lab/teardown-bond-ovs-lab.shOperating Systems:
- Ubuntu 20.04+ / Debian 11+
- RHEL 8+ / Rocky Linux 8+ / AlmaLinux 8+
- Fedora (recent releases)
Requirements:
- Linux kernel 4.x+ with bonding module
- NetworkManager (for bond wizard)
- Open vSwitch (for OVS wizard)
- Root/sudo access
- systemd-based system
Quick install (recommended):
# Clone repository
git clone https://github.com/DEC-LLC/CAAN.git
cd CAAN-System-Tools
# Run installation script
sudo ./scripts/install.shManual installation:
# Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y network-manager openvswitch-switch \
ethtool dialog zenity
# Install dependencies (RHEL/Fedora)
sudo dnf install -y NetworkManager openvswitch ethtool dialog zenity
# Make scripts executable
chmod +x bonding-wizrd/*.sh
chmod +x ovs-wizrd/*.shCreate an LACP bond:
$ sudo ./bonding-wizrd/nm-bond-wizard-0.4.5.sh --apply
# Wizard displays detected interfaces:
# enp1s0 - Intel I225-V 2.5Gb/s (up, link detected)
# enp2s0 - Intel 82574L 1Gb/s (up, link detected)
# Select interfaces: enp1s0 enp2s0
# Select bond mode: 802.3ad (recommended for your hardware)
# Configure IP: DHCP or static
# Add VLANs: (optional) 100,200,300
# Review plan and confirm
# Automatic backup created → Bond configured and activatedCreate an OVS bridge:
$ sudo ./ovs-wizrd/ovs-wizard-0.2.0.sh --apply
# Select operation: Create new bridge
# Bridge name: br0
# Add ports: eth2 eth3
# Configure bond: yes
# Bond mode: LACP
# Add VLANs: 10,20,30
# Review configuration → Apply changesRollback after problem:
# List available backups
sudo ./bonding-wizrd/nm-bond-wizard-0.4.5.sh --list-backups
# Rollback to most recent
sudo ./bonding-wizrd/nm-bond-wizard-0.4.5.sh --rollback
# Network configuration restored in seconds| Document | Description |
|---|---|
| Quick Start Guide | Get started in 5 minutes |
| User Guide | Complete usage instructions |
| Examples | Real-world configuration examples |
| Troubleshooting | Common issues and solutions |
| FAQ | Frequently asked questions |
| Document | Description |
|---|---|
| Architecture | System design and components |
| API Reference | Library and function reference |
| Integration Guide | Ansible, Puppet, Chef integration |
| Testing Guide | Lab setup and test procedures |
| Security | Security architecture and audit |
| Document | Description |
|---|---|
| Contributing Guide | How to contribute |
| Development Setup | Developer environment setup |
| Code Standards | Coding guidelines |
| Roadmap | Future development plans |
| Project Structure | Repository organization |
┌─────────────────────────────────────────────────────────────────┐
│ CAAN System Tools │
│ │
│ ┌───────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ nm-bond-wizard│ │ ovs-wizard │ │ Web Management │ │
│ │ (Production) │ │ (Beta) │ │ (Development) │ │
│ └───────┬───────┘ └──────┬───────┘ └─────────┬──────────┘ │
│ │ │ │ │
│ ┌───────┴──────────────────┴─────────────────────┴──────────┐ │
│ │ Shared Libraries & Services │ │
│ ├──────────────────────────────────────────────────────────┤ │
│ │ • validation_lib.sh - Multi-layer validation │ │
│ │ • ui_lib.sh - CLI/GUI/TUI abstraction │ │
│ │ • network_lib.sh - Discovery and introspection │ │
│ │ • backup_lib.sh - Backup and rollback framework │ │
│ │ • logging_lib.sh - Structured logging │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
┌──────────────────┴──────────────────┐
│ │
┌────▼─────────┐ ┌───────▼──────┐
│ NetworkManager│ │ Open vSwitch │
│ (nmcli) │ │ (ovs-vsctl) │
└────┬─────────┘ └───────┬──────┘
│ │
└──────────────────┬──────────────────┘
│
┌──────▼──────┐
│ Linux Kernel│
│ Network │
│ Stack │
└─────────────┘
- Shell: Bash 4.0+ for wizard scripts
- Python: Flask web backend (planned)
- JavaScript: Vue.js frontend (planned)
- Testing: Bash test framework with Podman/OVS lab
- CI/CD: GitHub Actions
- Documentation: Markdown with PDF generation
Status: ✅ Production Ready (Bond Wizard) | 🔄 Beta (OVS Wizard)
Features:
- nm-bond-wizard v0.4.5 with security hardening
- ovs-wizard v0.2.0 with core features
- Shared validation library
- Comprehensive testing framework
- Multi-node lab environment
- CI/CD automation
Focus: OVS Wizard Feature Completion
- OVS wizard v1.0 with all core features
- Template system for common configurations
- Enhanced multi-node lab support
- Web UI alpha release
- Ansible/Puppet modules
- Container images for deployment
Focus: Web Management & Automation
- Production-ready web UI
- REST API for automation
- Multi-node centralized management
- Configuration templates library
- Monitoring and alerting integration
- Advanced troubleshooting tools
Focus: Enterprise Features
- High-availability clustering
- Configuration drift detection
- Policy-based automation
- Integration with SDN controllers
- Compliance and audit reporting
- Professional support options
See ROADMAP.md for detailed development plans.
CAAN includes comprehensive testing capabilities:
Lab Environment:
- Podman-based container lab with systemd
- Open vSwitch configured as LACP-capable switch
- Multiple network interfaces via veth pairs
- Fast deployment (30-60s) and reset (5s)
Test Suite:
- 25+ test scenarios covering all features
- Automated bond and OVS configuration tests
- IPv4/IPv6 dual-stack testing
- Failover and reliability testing
- Security and validation testing
Coverage:
- 100% feature coverage for bond wizard
- 85% feature coverage for OVS wizard (growing)
- Automated regression testing
- Performance benchmarking
Quick validation (2-3 minutes):
sudo tests/validate.shFull test suite (10-12 minutes):
sudo tests/test-wizard.shOVS-specific tests:
sudo tests/test-ovs-wizard.shReliability testing:
sudo tests/test-bond-reliability.sh --iterations 100See TESTING.md for complete testing documentation.
We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing your use cases, your contributions make CAAN better for everyone.
- Code: Bug fixes, new features, optimizations
- Documentation: Tutorials, examples, translations
- Testing: Bug reports, test cases, lab scenarios
- Community: Answer questions, share experiences
- Advocacy: Blog posts, talks, case studies
- Read the Contributing Guide
- Check Good First Issues
- Join the Discussion Forums
- Fork the repo and start coding!
# Fork and clone
git clone https://github.com/YOUR-USERNAME/CAAN-System-Tools.git
cd CAAN-System-Tools
# Create feature branch
git checkout -b feature/my-contribution
# Make changes and test
sudo tests/validate.sh
# Commit and push
git commit -m "feat: add new feature"
git push origin feature/my-contribution
# Create pull request on GitHubSee CONTRIBUTING.md for detailed guidelines.
- GitHub Discussions: https://github.com/DEC-LLC/CAAN/discussions
- Issue Tracker: https://github.com/DEC-LLC/CAAN/issues
- Matrix Chat: #caan-system-tools:matrix.org (planned)
- Mailing List: caan-users@googlegroups.com (planned)
- Documentation: Start with Quick Start Guide
- FAQ: Check Frequently Asked Questions
- Discussions: Ask questions in GitHub Discussions
- Issues: Report bugs via GitHub Issues
CAAN is committed to providing a welcoming and inclusive environment. All participants are expected to adhere to our Code of Conduct.
Contributors are recognized in:
- CONTRIBUTORS.md - All contributors list
- Release notes for each version
- Git commit history and GitHub profiles
CAAN takes security seriously. We follow industry best practices:
- Input Validation: Multi-layer validation of all inputs
- Privilege Management: Principle of least privilege
- Audit Logging: Complete audit trails
- Secure Defaults: Safe configurations by default
- Regular Audits: Ongoing security assessments
Do not report security vulnerabilities through public GitHub issues.
Please report security vulnerabilities to:
- Email: security@diwanconsulting.com
- PGP Key: [Available on request]
Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested remediation (if any)
See SECURITY.md for complete security policy.
CAAN System Tools is licensed under the Apache License 2.0.
Commercial support, training, and consulting available through:
Diwan Enterprise Consulting LLC
- Website: https://diwanconsulting.com
- Email: mdiwan@diwanconsulting.com
- Services: Custom development, enterprise support, training
| Metric | Value |
|---|---|
| Lines of Code | 25,000+ |
| Shell Scripts | 35+ (10,000+ lines) |
| Python Code | 5,000+ lines (web backend) |
| Documentation | 50+ files (20,000+ lines) |
| Test Scenarios | 25+ comprehensive tests |
| Test Coverage | 95%+ |
| Supported Platforms | 5+ Linux distributions |
| Active Contributors | Growing (see CONTRIBUTORS.md) |
CAAN System Tools is built on the shoulders of giants:
- NetworkManager Team - NetworkManager is the foundation of our bond wizard
- Open vSwitch Team - OVS provides the SDN capabilities we build upon
- Linux Kernel Team - The networking stack that powers everything
- Open Source Community - Countless tools and libraries we depend on
Special thanks to:
- Early adopters and beta testers
- Contributors who submitted patches and improvements
- Everyone who reported bugs and provided feedback
- NetworkManager: https://networkmanager.dev/
- Open vSwitch: https://www.openvswitch.org/
- Podman: https://podman.io/
- Linux Bridge Utils: https://wiki.linuxfoundation.org/networking/bridge
CAAN System Tools is developed and maintained by Diwan Enterprise Consulting LLC with contributions from the open-source community.
Mission: Democratize advanced network configuration by providing professional-grade tools that are safe, intelligent, and accessible to everyone.
Tagline: OPEN IDEAS
Founded: 2026 Lead Developer: Madhav Diwan Organization: Diwan Enterprise Consulting LLC Website: https://diwanconsulting.com
CAAN System Tools — Professional networking tools for everyone
Safe • Intelligent • Open Source
Version 0.6.0 | February 2026 | Diwan Enterprise Consulting LLC