ezlb

English | 中文

A lightweight Layer-4 TCP/UDP load balancer based on Linux IPVS, using declarative reconcile mode to dynamically manage IPVS services.

Features

• IPVS Kernel-Level Load Balancing: High-performance Layer-4 TCP/UDP forwarding powered by Linux IPVS
• Declarative Reconcile: Automatically compares desired state with actual IPVS rules and applies incremental changes
• Multiple Scheduling Algorithms: Round Robin (rr), Weighted Round Robin (wrr), Least Connection (lc), Weighted Least Connection (wlc), Destination Hashing (dh), Source Hashing (sh)
• TCP & HTTP Health Checks: Independent health check configuration per service, supporting TCP connection probes and HTTP GET probes with configurable path and expected status code
• FullNAT / SNAT Support: Optional per-service FullNAT mode via IPVS NAT + iptables SNAT/MASQUERADE, with automatic nftables compatibility on iptables-nft backends
• Hot Config Reload: File changes automatically trigger reconciliation without restart

Quick Start

Build

make build

Cross-compile for Linux:

make build-linux

Configuration

Create a config file config.yaml:

global:
  log_level: info
  cleanup_on_exit: true    # Remove managed IPVS services and EZLB-SNAT iptables chain on exit (default: true)

services:
  - name: web-service
    listen: 10.0.0.1:80
    protocol: tcp
    scheduler: wrr
    health_check:
      enabled: true
      type: tcp              # optional: tcp (default), http
      interval: 5s
      timeout: 3s
      fail_count: 3
      rise_count: 2
    backends:
      - address: 192.168.1.10:8080
        weight: 5
      - address: 192.168.1.11:8080
        weight: 3

  - name: api-service
    listen: 10.0.0.1:443
    protocol: tcp
    scheduler: wlc
    health_check:
      enabled: true
      type: http             # HTTP health check
      interval: 10s
      timeout: 5s
      fail_count: 5
      rise_count: 3
      http_path: /healthz            # default: /
      http_expected_status: 200      # default: 200
    backends:
      - address: 192.168.2.10:8443
        weight: 1
      - address: 192.168.2.11:8443
        weight: 1

  - name: dns-service
    listen: 10.0.0.2:53
    protocol: udp            # UDP load balancing
    scheduler: rr
    full_nat: true           # Enable FullNAT (IPVS NAT + iptables SNAT)
    snat_ip: 10.0.0.2        # Source IP for SNAT; omit for MASQUERADE
    health_check:
      enabled: false
    backends:
      - address: 192.168.3.10:53
        weight: 1
      - address: 192.168.3.11:53
        weight: 1

Usage

# Daemon mode
sudo ezlb start -c config.yaml

# Single reconcile pass
sudo ezlb once -c config.yaml

# Show version
ezlb -v

Testing

# Run unit tests (macOS/Linux)
make test

# Run all tests (Linux, requires root)
make test-linux

# Run e2e tests (Linux, requires root)
make test-e2e

Project Structure

ezlb/
├── cmd/ezlb/            # Entry point, CLI commands
├── pkg/
│   ├── config/           # Config management (loading, validation, hot reload)
│   ├── lvs/              # IPVS management (operations, reconcile)
│   ├── healthcheck/      # Health checking (TCP & HTTP probes)
│   ├── snat/             # SNAT/FullNAT management (iptables rules)
│   └── server/           # Server orchestration (lifecycle management)
├── tests/e2e/            # End-to-end tests
├── examples/             # Example configurations
└── Makefile