Highly Available Load Balancing,
Visualized & Simplified.

OSBal is a visual control panel for HAProxy, Keepalived, and Stunnel4. Convert any physical machine, VM, or Raspberry Pi into a secure, layer 7 load-balancing appliance in minutes.

Get Started Now View Source Code

Active-Passive VRRP High-Availability Workflow

Client Traffic Virtual IP (VIP) Keepalived VRRP Primary Failover OSBal Master HAProxy + WAF OSBal Backup Standby Node Backend Server 01 Backend Server 02

Why OSBal? Serving a Core Niche

A load balancer built specifically for environments where cost, performance efficiency, and offline resilience are paramount.

Zero Bandwidth Fees

Unlike cloud load balancers (AWS ALB, Azure, GCP) that charge subscription hours plus data egress metrics, OSBal runs on your own hardware or VMs with unlimited bandwidth for free.

Offline & Edge Ready

Perfect for private subnets, secure military networks, edge installations, or homelabs. OSBal functions 100% locally and does not depend on cloud APIs or WAN connection links.

Low Resource Footprint

Proprietary enterprise VMs require several cores and gigabytes of RAM. OSBal runs high-performance C binaries (HAProxy & Keepalived) using less than 512MB RAM on a Raspberry Pi.

OSBal vs. Other Open Source Alternatives

How OSBal compares directly to other open-source load balancers and proxy managers in the ecosystem.

Feature OSBal Roxy-WI Nginx Proxy Manager Raw CLI Configurations
Clustering / Failover (VRRP) Yes (Built-in active-passive config) Yes (Complex multi-daemon) No (Must setup manually) Manual script configuration
Supported Proxy Engines HAProxy & Stunnel4 HAProxy, Nginx, Keepalived Nginx only Any (HAProxy, Stunnel, Nginx)
License & Restrictions 100% Free (No limits) Commercially limited / Paid subscription 100% Free 100% Free
Resource Overhead Ultra Low (<512MB RAM) Heavy (requires Python backend) Medium (NodeJS & database) Ultra Low
Setup & Maintenance Easy (1-line script & UI) Hard (requires database & config servers) Easy Hard (Manual text edits only)

Roxy-WI Analysis

Pros: Highly comprehensive, supports multiple load balancers, and has advanced monitoring dashboards.

Cons: Heavy Python/Flask overhead. Advanced features and updates are locked behind paid commercial licenses or memberships. Setup is complex and time-consuming.

Nginx Proxy Manager Analysis

Pros: Extremely user-friendly UI, simple setup, and integrated Let's Encrypt SSL certificate generation.

Cons: Limited strictly to Nginx. Lacks Keepalived VRRP failover config, meaning you cannot easily set up active-passive redundant cluster load balancers out of the box.

Appliance Highlights

OSecure AI Integration

Activate OSecure directly from your Admin GUI. Automatically configures the background sidecar daemon (osecure-agentd) to compute Z-score traffic anomalies, triage requests utilizing Google Gemini, prevent outbound database exfiltration leaks, and sync rules to AWS WAF / GCP Cloud Armor.

Realtime Stats Terminal

Inspect active connection stats, query response times, and filter blocks. Features a simulated live Access Logs terminal and stress simulator to test threshold behaviors.

3-Step Setup Wizard

Dynamic package diagnostics list automatically verifies that HAProxy, Keepalived, and Stunnel are installed, guiding you through admin setups and network interfaces.

Visual Load Balancing

Create frontends, backends, and assign server nodes using balancing strategies like Round-Robin, Session Cookie-based stickiness, or Client IP hashing from a clean web form.

Config Syntax Validator

Validate compilation syntax before reloads. Invokes the official `haproxy -c` config check directly from the web console, preventing bad parameters from crashing active services.

Backend Reachability Tester

Run instant socket reachability tests from the load balancer appliance to backend IPs and ports. Verify connection latency (in ms) or receive detailed system-level socket failure reports.

Get Started in Your Terminal

Ready to deploy? Copy the script below to install system dependencies, download the OSBal interface, configure system permissions, and launch the web server automatically.

curl -sSL https://raw.githubusercontent.com/chrissiefken/osbal/master/scripts/deploy.sh | bash

Developer & Clustering API

OSBal exposes a fully featured REST API on every node. This API allows external orchestration tools to export configuration states, deploy certificates, update blocklists, or synchronize redundant HA pairs.

API Authentication Header

All external API requests must authorize by sending the cluster's shared secret API key. Add the key under one of the following HTTP headers. Requests without valid keys will receive a 401 Unauthorized response.

X-OSBAL-API-KEY: your_configured_api_key
(Note: This key must match the 'Shared API Key' configured in the High Availability Clustering tab.)

GET /api/config.php

Export Configuration

Retrieves the complete appliance database structure. The output is a consolidated JSON object containing service configurations, SSL certificates, global IP blacklists, and HA router parameters.

HTTP Response Schema (200 OK):

{ "success": true, "config": { "services": { "service_unique_id": { "id": "service_unique_id", "name": "Production Web App", "ip": "*", "port": 80, "mode": "http", "balance": "roundrobin", "waf_enabled": true, "block_sqli": true, "block_xss": true, "rate_limit": false, "rate_limit_type": "tarpit", "rate_limit_max": 100, "rate_limit_delay": 5, "servers": { "node_unique_id": { "id": "node_unique_id", "name": "web-01", "ip": "192.168.1.15", "port": 8080, "weight": 1, "check": true } } } }, "ssl": { "example.com": { "name": "example.com", "cert_pem": "-----BEGIN CERTIFICATE-----\n...", "key_pem": "-----BEGIN PRIVATE KEY-----\n...", "bindIp": "*", "bindPort": 443, "targetPort": 80, "pemPath": "/etc/stunnel/certs/example.com.pem" } }, "blacklist": [ "192.168.1.180", "203.0.113.15" ], "ha_settings": { "enabled": true, "role": "MASTER", "virtual_ip": "192.168.1.250", "interface": "eth0", "router_id": 51, "auth_pass": "osbal_vrrp", "partner_ip": "192.168.1.102", "api_key": "your_api_key" } } }
Example cURL Command:
curl -H "X-OSBAL-API-KEY: your_api_key" http://192.168.1.101/api/config.php

POST /api/config.php

Import & Sync Config

Overwrites the local appliance configuration database with the incoming JSON payload, triggers a compilation of configuration files, and restarts services.

Note on Clustering Role Swap: If the incoming payload contains ha_settings, OSBal automatically inverts the VRRP role (e.g. if the incoming role is MASTER, the receiving local node configures itself as BACKUP). This prevents duplicate MASTER conflicts.

HTTP Request Payload format:

Send a JSON payload matching the structure exported by the GET endpoint (with optional services, ssl, blacklist, or ha_settings objects).

Example cURL Command:
curl -X POST -H "Content-Type: application/json" -H "X-OSBAL-API-KEY: key" -d @backup.json http://192.168.1.102/api/config.php

Detailed Configuration Schema Reference

Below are all the options supported inside the import JSON configuration payload. You can choose to pass any combination of these top-level objects to partially update or fully overwrite configuration areas.

Top-Level Properties
  • services (object): Optional. Dictionary of virtual services keyed by unique service ID.
  • ssl (object): Optional. Dictionary of SSL certificate profiles keyed by domain/profile name.
  • blacklist (array): Optional. Flat array of client IP addresses to block globally via WAF.
  • ha_settings (object): Optional. Cluster High Availability configuration parameters.
services.* Property Reference
id
string Required. Unique alphanumeric identifier for the service.
name
string Required. Friendly descriptive name of the load balancer listener.
ip
string IP address/interface the service listens on. Use * to bind to all available interfaces.
port
integer Port number that client traffic connects to (e.g. 80, 8080).
mode
string Protocol mode. Must be either "http" (layer 7 balancing) or "tcp" (layer 4 raw stream balancing).
balance
string Load distribution strategy. Options: "roundrobin" (alternates requests), "ip" (source IP affinity), or "cookie" (inserts session cookie, HTTP mode only).
waf_enabled
boolean Enables WAF signature inspection and IP blacklist filtering for this frontend. (HTTP mode only)
block_sqli
boolean Blocks SQL Injection signatures (e.g. SELECT, UNION, DROP) in query parameters.
block_xss
boolean Blocks Cross-Site Scripting signatures (e.g. <script>, onerror, alert()) in query parameters.
rate_limit_type
string WAF mitigation action. Choose "deny" to immediately return HTTP 403 Forbidden, or "tarpit" to hold connection slot.
rate_limit_delay
integer Tarpit delay in seconds (e.g. 5) to hold SQLi/XSS requests if rate_limit_type is set to "tarpit".
ssl_enabled
boolean Enables TLS/SSL decryption (SSL termination) for this frontend service using Stunnel.
ssl_port
integer The HTTPS port that Stunnel listens on to receive TLS traffic (e.g. 443).
ssl_cert_name
string The certificate profile name (corresponding to a key in the ssl dictionary) to bind.
servers
object Dictionary of target backend node server pools, keyed by a unique node identifier.
services.*.servers.* Property Reference
id
string Required. Unique alphanumeric identifier for this server node.
name
string Required. User-friendly hostname or label for the backend server.
ip
string Required. The target destination IPv4 address (e.g. 192.168.1.15) of the backend host.
port
integer Required. Port the backend server is running on (e.g. 8080).
weight
integer Traffic distribution weight (1 to 256). Higher weights route proportional share of connections.
check
boolean Enables HAProxy layer 7/TCP active health checking on the node. Out-of-service nodes are automatically removed.
ssl.* Property Reference
name
string Required. Profile name matching the key in the ssl dictionary (typically a domain name).
cert_pem
string Required. Raw PEM-encoded certificate chain (includes public cert and intermediates). Use literal newlines (\n).
key_pem
string Required. Raw PEM-encoded private key. MUST match the certificate file.
bindIp
string Bind IP address for Stunnel decryption listening socket. Usually "*".
bindPort
integer TLS port (e.g. 443). Traffic sent here decrypted and forwarded internally.
targetPort
integer Local loopback port the decrypted stream is forwarded to (connecting to the virtual service's bind port).
pemPath
string Target destination file path where the combined certificate and key block is written on disk.
ha_settings Property Reference
enabled
boolean Enables Keepalived VRRP failover clustering daemon configurations.
role
string Preferred state node: "MASTER" or "BACKUP". Note: On node-to-node replication import, this role will automatically invert to prevent split-brain VIP state.
virtual_ip
string Floating virtual IP address (e.g. 192.168.1.250) shared across the cluster.
interface
string The physical network card interface descriptor to bind (e.g. "eth0", "en0").
router_id
integer The unique VRRP group cluster ID identifier (range 1 to 255).
auth_pass
string VRRP cluster protocol password header. Must match on both peer nodes.
partner_ip
string IP address of the secondary clustering peer node (e.g. 192.168.1.102).
api_key
string Shared API secret key used for node validation.

HTTP Response Schema (200 OK):

{ "success": true, "message": "Configuration synchronized and reloaded successfully." }

API Response Status Codes Reference

HTTP Code Meaning Condition JSON Response Example
200 OK Request Success Config exported or successfully imported & reloaded. {"success":true,"message":"..."}
400 Bad Request Invalid Payload JSON parsing failed or parameters are missing. {"success":false,"message":"Invalid payload"}
401 Unauthorized Auth Failure Missing or incorrect X-OSBAL-API-KEY header. {"success":false,"message":"Unauthorized"}
405 Method Not Allowed Invalid Method Endpoint queried using PUT, DELETE, or other method. {"success":false,"message":"Unsupported method"}
500 Server Error Reload Failed Config stored locally, but daemon reload command failed. {"success":false,"message":"Reload failed: ..."}

About OSBal Project

OSBal was designed to fill a crucial gap in modern infrastructure: providing an elegant, visual, and secure management platform for bare-metal, virtualized, and edge load-balancing appliances. Built entirely on top of industry-standard C-based engines (HAProxy, Keepalived VRRP failover, and Stunnel4 SSL termination), OSBal delivers enterprise reliability with a lightweight resource footprint capable of running on Raspberry Pi or virtual private servers.

HAProxy 2.x+ Keepalived VRRP Stunnel4 SSL

Looking for Enterprise Support?

Need help deploying OSbal in highly sensitive corporate environments or scaling out to cloud infrastructures? The OSecure team provides dedicated enterprise support contracts, design consulting, and security escalation SLA response.

Unlock advanced machine-learning capabilities, time-series exfiltration defense, and automated edge synchronization to AWS WAF & GCP Armor with the OSecure addon integration.

Get OSecure Support Explore OSecure AI