{"id":48832306,"url":"https://github.com/1999azzar/load_balancer_tool","last_synced_at":"2026-04-14T21:01:58.244Z","repository":{"id":332150374,"uuid":"1132589572","full_name":"1999AZZAR/load_balancer_tool","owner":"1999AZZAR","description":"This package provides tools to implement Layer 3 load balancing on a Linux system using iproute2 and nftables. It allows for the simultaneous use of multiple network interfaces (e.g., Wi-Fi, Ethernet, USB tethering) to distribute outbound traffic.","archived":false,"fork":false,"pushed_at":"2026-01-12T16:57:25.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-12T22:24:22.802Z","etag":null,"topics":["linux","load-balancer","networking"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1999AZZAR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-12T07:12:45.000Z","updated_at":"2026-01-12T16:57:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1999AZZAR/load_balancer_tool","commit_stats":null,"previous_names":["1999azzar/load_balancer_tool"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/1999AZZAR/load_balancer_tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fload_balancer_tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fload_balancer_tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fload_balancer_tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fload_balancer_tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1999AZZAR","download_url":"https://codeload.github.com/1999AZZAR/load_balancer_tool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fload_balancer_tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31815080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","load-balancer","networking"],"created_at":"2026-04-14T21:01:56.279Z","updated_at":"2026-04-14T21:01:58.233Z","avatar_url":"https://github.com/1999AZZAR.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux Network Load Balancer\n\nThis package provides advanced tools to implement Layer 3 load balancing on a Linux system using `iproute2` and `nftables`. It allows for the simultaneous use of multiple network interfaces (e.g., Wi-Fi, Ethernet, USB tethering) to distribute outbound traffic with enterprise-grade features including real-time monitoring, health checks, session affinity, and graceful failover.\n\n## Table of Contents\n\n- [Contents](#contents)\n- [System Requirements](#system-requirements)\n- [Installation (Recommended)](#installation-recommended)\n- [Installation (Manual Service Method)](#installation-manual-service-method)\n- [Configuration](#configuration)\n  - [Core Settings](#core-settings)\n  - [Real-time Monitoring](#real-time-monitoring)\n  - [Health Checks](#health-checks)\n  - [Connection Management](#connection-management)\n  - [Failover Control](#failover-control)\n  - [Neighbor Monitoring](#neighbor-monitoring)\n  - [Logging \u0026 Metrics](#logging--metrics)\n- [Usage (Standalone Script)](#usage-standalone-script)\n- [Testing](#testing)\n- [Metrics \u0026 Monitoring](#metrics--monitoring)\n- [Technical Details](#technical-details)\n- [Uninstallation](#uninstallation)\n- [License](#license)\n\n## Contents\n\n1. `universal_load_balancer.sh`: A standalone script for one-time configuration.\n2. `net_autobalance.sh`: The core logic script for the systemd service with advanced features.\n3. `net_balancer.service`: The systemd unit file for persistent background monitoring.\n4. `test_harness.sh`: Comprehensive test harness for simulating failure scenarios.\n5. `install.sh`: Installation script for automated setup.\n6. `uninstall.sh`: Complete uninstallation script to remove all components.\n\n## System Requirements\n\n- Root privileges (sudo).\n- `iproute2` (installed by default on most distributions).\n- `nftables` (for NAT/Masquerading).\n- `bash`.\n\n## Installation (Recommended)\n\nThe easiest way to install or update the load balancer is using the provided installation script:\n\n```bash\nsudo ./install.sh\n```\n\nThis script will:\n\n- Detect if the service is already installed and perform an update if necessary.\n- Copy scripts to `/usr/local/bin/`.\n- Set up and start the systemd service.\n\n## Installation (Manual Service Method)\n\nIf you prefer manual steps:\n\n1. Copy the script to the executable path:\n   \n   ```bash\n   sudo cp net_autobalance.sh /usr/local/bin/\n   sudo chmod +x /usr/local/bin/net_autobalance.sh\n   ```\n\n2. Copy the service file to the systemd directory:\n   \n   ```bash\n   sudo cp net_balancer.service /etc/systemd/system/\n   ```\n\n3. Reload the systemd daemon, enable the service on boot, and start it:\n   \n   ```bash\n   sudo systemctl daemon-reload\n   sudo systemctl enable net_balancer.service\n   sudo systemctl start net_balancer.service\n   ```\n\n4. Verify status:\n   \n   ```bash\n   sudo systemctl status net_balancer.service\n   ```\n\n## Configuration\n\nThe load balancer can be configured via environment variables or by editing the script directly. Key configuration options:\n\n### Core Settings\n- `LB_TABLE=200`: Routing table ID for load balancing\n- `LB_PREF=90`: IP rule preference for load balancing\n\n### Real-time Monitoring\n- `DEBOUNCE_TIME=2`: Seconds to wait after network events before reconfiguration\n\n### Health Checks\n- `HEALTH_CHECK_ENABLED=true`: Enable/disable active health monitoring\n- `HEALTH_CHECK_INTERVAL=30`: Seconds between health checks\n- `HEALTH_CHECK_TIMEOUT=3`: Timeout for health probes\n- `HEALTH_CHECK_FAILURE_THRESHOLD=2`: Consecutive failures before marking interface down\n- `HEALTH_CHECK_RECOVERY_THRESHOLD=1`: Consecutive successes before marking interface up\n- `HEALTH_PROBE_TARGET=\"1.1.1.1\"`: Target for connectivity checks\n- `HEALTH_PROBE_PORT=53`: TCP port for health probes\n\n### Connection Management\n- `CONNECTION_DRAINING_ENABLED=true`: Enable graceful connection draining\n- `SESSION_AFFINITY_ENABLED=true`: Enable sticky routing per connection\n- `CONSISTENT_NAT_ENABLED=true`: Ensure consistent source IPs\n\n### Failover Control\n- `FAILOVER_HYSTERESIS_ENABLED=true`: Enable hysteresis to prevent flapping\n- `FAILOVER_BACKOFF_BASE=30`: Base backoff time in seconds\n- `FAILOVER_BACKOFF_MAX=300`: Maximum backoff time\n- `FAILOVER_HOLD_DOWN=60`: Hold-down period before re-enabling interfaces\n\n### Neighbor Monitoring\n- `NEIGHBOR_REACHABILITY_ENABLED=true`: Monitor ARP/NDP for gateway reachability\n\n### Logging \u0026 Metrics\n- `LOG_LEVEL=\"info\"`: Logging level (debug/info/warn/error)\n- `METRICS_ENABLED=false`: Enable Prometheus metrics\n- `METRICS_PORT=9090`: Port for metrics HTTP server\n- `METRICS_FILE=\"/var/run/load_balancer_metrics.prom\"`: Metrics file path\n\n## Usage (Standalone Script)\n\nIf you prefer not to install the service, you can run the configuration once manually:\n\n```bash\nsudo ./universal_load_balancer.sh\n```\n\n## Testing\n\nUse the included test harness to simulate various failure scenarios:\n\n```bash\nsudo ./test_harness.sh status                    # Show current status\nsudo ./test_harness.sh down-up wlan0 30          # Bring interface down then up\nsudo ./test_harness.sh flap eth0 5               # Simulate route flapping\nsudo ./test_harness.sh neighbor-fail eth0        # Simulate neighbor failure\nsudo ./test_harness.sh health-block 30           # Block health check target\nsudo ./test_harness.sh comprehensive             # Run full test suite\n```\n\n## Metrics \u0026 Monitoring\n\nWhen `METRICS_ENABLED=true`, the service exposes Prometheus metrics on the configured port:\n\n```\n# HELP load_balancer_log_messages_total Total number of log messages\n# TYPE load_balancer_log_messages_total counter\nload_balancer_log_messages_total 42\n\n# HELP load_balancer_active_interfaces Number of active interfaces\n# TYPE load_balancer_active_interfaces gauge\nload_balancer_active_interfaces 2\n```\n\nAccess metrics at: `http://localhost:9090/metrics`\n\n## Technical Details\n\n- **Real-time Monitoring:** Uses `ip monitor route link` for instant detection of network changes instead of polling.\n- **Health Checks:** Active per-interface connectivity monitoring with TCP probes, configurable thresholds, and failure recovery.\n- **Connection Draining:** Graceful handling of existing connections during interface failures to prevent session drops.\n- **Session Affinity:** Optional sticky routing ensures consistent interface usage per connection flow.\n- **Failover Hysteresis:** Prevents flapping with exponential backoff, hold-down periods, and configurable recovery logic.\n- **Consistent NAT:** Per-interface SNAT ensures connections maintain the same source IP throughout their lifetime.\n- **Neighbor Reachability:** ARP/NDP monitoring detects layer-2 gateway reachability issues.\n- **Routing:** Separate routing tables (IDs 100+) for each interface ensure correct return-path routing.\n- **Load Balancing:** Multipath default routes with configurable weighting distribute connections across healthy interfaces.\n- **NAT:** `nftables` masquerading with connection tracking for consistent address translation.\n- **Metrics \u0026 Monitoring:** Optional Prometheus metrics endpoint and structured logging with configurable levels.\n\n## Uninstallation\n\nTo completely remove the load balancer and restore your system to its original state:\n\n```bash\nsudo ./uninstall.sh\n```\n\nThis script will:\n- Stop and disable the systemd service\n- Remove all installed files\n- Clean up routing rules and tables\n- Remove nftables rules\n- Delete metrics files\n- Provide a detailed status report\n\nThe uninstallation is designed to be safe and thorough, ensuring no leftover configuration affects your system.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1999azzar%2Fload_balancer_tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1999azzar%2Fload_balancer_tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1999azzar%2Fload_balancer_tool/lists"}