Listeners & Backends

Overview

Listeners and backends are the foundation of coreX Platform’s traffic routing. A listener (HAProxy frontend) accepts inbound connections on a bind address and port. A backend is a pool of upstream servers that the listener forwards traffic to, using a configurable load balancing algorithm and health checks.

Listeners support HTTP/1.1, HTTP/2 (h2 and h2c), and HTTP/3 (QUIC). TLS termination is configured per listener and is covered in the Certificates & TLS guide.

Listeners

Creating a Listener

1. Navigate to Core > Listeners
2. Click Add Listener
3. Configure the bind address and port (e.g. *:443)
4. Select the protocol mode (HTTP or TCP)
5. Enable TLS if needed and select a certificate
6. Click Save and Apply Changes

Listener Properties

HTTP/2 and QUIC

HTTP/2 is enabled by adding alpn h2,http/1.1 to the TLS bind line. This allows the listener to negotiate HTTP/2 with supporting clients while remaining compatible with HTTP/1.1.

HTTP/3 (QUIC) requires an additional UDP bind on the same port. When QUIC is enabled on a listener, coreX Platform:

• Adds a UDP bind directive
• Emits an Alt-Svc header on HTTP/1.1 and HTTP/2 responses advertising the QUIC endpoint
• Configures the QUIC connection migration and retry logic

SNI-based Routing

For TLS listeners with multiple hostnames, coreX Platform generates SNI-based routing using crt directories or crt-list files. Each certificate is matched by its CN/SAN, and traffic is routed to the appropriate backend based on the SNI hostname.

Backends

Creating a Backend

1. Navigate to Core > Backends
2. Click Add Backend
3. Enter a name (e.g. web-servers)
4. Add server entries (name, address, port)
5. Select a load balancing algorithm
6. Configure health checks if needed
7. Click Save and Apply Changes

Load Balancing Algorithms

Server Properties

Each server in a backend has:

Health Checks

Health checks verify that backend servers are responsive. coreX Platform supports:

• TCP check — verify the TCP connection succeeds (default)
• HTTP check — send an HTTP request and check the response status
• Custom check path — the URL path to check (e.g. /health)
• Expected status — the HTTP status code that indicates health (e.g. 200)

Session Persistence (Stick Tables)

For sessions that must stick to a single server, coreX Platform supports stick-table-based persistence:

• stick-table type — ip, string, binary (what to key on)
• stick on — the expression to match (e.g. src for client IP)
• expire — how long to remember the stickiness (e.g. 30m)

HTTP Connection Reuse

Each backend has an optional http-reuse setting that controls server-side connection pooling. HAProxy’s default is safe (reuse idle connections when safe). Override per backend:

FastCGI

FastCGI applications (PHP-FPM, etc.) are configured separately from regular HTTP backends and attached to a backend via the backend’s FastCGI App field. A FastCGI app defines how HAProxy talks to the FastCGI process: the document root, index file, path-info handling, connection options, and arbitrary FastCGI parameters.

FastCGI App Properties

Attaching a FastCGI App to a Backend

1. Create the FastCGI app under Core > Load Balancing > FastCGI
2. Create or edit a backend under Core > Load Balancing > Backends
3. Set the backend Protocol to fastcgi
4. Set FastCGI App to the app you created
5. Add the FastCGI server(s) (e.g. php-fpm at 127.0.0.1:9000)
6. Save and Apply

Step-by-Step: Route to a PHP-FPM Backend

1. Create the FastCGI app:

   • Navigate to Core > Load Balancing > FastCGI, click Add FCGI App
   • Name: php-app
   • Docroot: /var/www/html
   • Index: index.php
   • Keep connection open: enabled
   • Add any FastCGI params your app needs (e.g. SCRIPT_FILENAME = /var/www/html/index.php)
   • Save

2. Create the backend:

   • Navigate to Core > Load Balancing > Backends, click Add Backend
   • Name: php-fpm
   • Protocol: FastCGI
   • FastCGI App: php-app
   • Add server: php-fpm at 127.0.0.1:9000
   • Save

3. Create the listener:

   • Navigate to Core > Listeners, click Add Listener
   • Name: web-http
   • Bind: *:80
   • Mode: http
   • Default backend: php-fpm
   • Save

4. Apply:

   • Click Apply Changes
   • Verify with curl http://localhost/

Step-by-Step: Create a TLS Listener with Two Backends

1. Create the primary backend:

   • Navigate to Core > Backends, click Add Backend
   • Name: web-primary
   • Add servers: web1 at 10.0.0.1:8080, web2 at 10.0.0.2:8080
   • Algorithm: roundrobin
   • Enable HTTP health checks on /health, expect 200
   • Save

2. Create a fallback backend:

   • Add another backend named web-fallback
   • Add server: fallback1 at 10.0.0.10:8080, mark as backup
   • Save

3. Create the listener:

   • Navigate to Core > Listeners, click Add Listener
   • Name: web-https
   • Bind: *:443
   • Mode: http
   • Enable TLS, select your certificate
   • Enable HTTP/2
   • Default backend: web-primary
   • Save

4. Apply:

   • Click Apply Changes
   • Verify with curl -k https://localhost/

Verification

# Check HAProxy is listening
ss -tlnp | grep :443

# Test HTTP/2
curl -k --http2 https://localhost/

# Check backend health
curl -k https://localhost/haproxy?stats

# Verify load balancing (multiple requests)
for i in $(seq 1 10); do curl -k -s -o /dev/null -w '%{remote_ip}\n' https://localhost/; done

Next Steps

• Certificates & TLS — Bind TLS certificates to listeners
• Security Rules — Add access control rules
• Metrics & Logging — Monitor traffic and backend health