Skip to content


Lobby leverages the Linux kernels networking stack for network traffic processing and therefore the load balancing is not performed at the application layer, but at the kernel level.

To set up the kernel networking stack, Lobby uses the netfilter framework through the nftables Linux kernel subsystem.

Lobby System Diagram

Network packet processing with Lobby

All of the configuration interpretation, upstream health checking, DNS resolution and respective traffic routing orchestration are peformed by Lobby. This approach is perfectly sufficient to implement comprehensive and efficient load balancing capabilities.

Concepts and Definitions

These are some of the key concepts and definitions in Lobby's context.

Lobby Concepts

Lobby conceptual representation


A target is where the traffic is being expected at the Lobby host. Currently a target is only defined by the network protocol, such as TCP, and a network port. Each target must be unique.

Targets use upstream groups to load balance traffic.

Definition Description
name unique name representing the target
protocol the network protocol [tcp]
port unique port for the specified protocol
upstream_group the upstream group object linked to the target

Upstream Groups

An upstream group is a collection of one or more upstreams associated to one target. The definition of the distribution mode of the traffic across upstreams is done by an upstream group.

Definition Description
name unique name representing the upstream group
distribution traffic distribution mode [round-robin]
upstreams list of upstream objects linked to the upstream group

Distribution Modes


All outgoing traffic is spread evenly across all of the available upstreams.


An upstream is a destination to which the traffic will be proxied to. Upstreams are defined by a network address (host) and a network port (port).

Definition Description
name unique name representing the upstream
host upstream network address as IPv4 or FQDN
port upstream network port
health_check health check object linked to the upstream
dns dns object linked to the upstream

The health_check and dns definitions for the upstream are optional.

In case no health_check object is linked to the upstream, the upstream will always be considered to be available to receive traffic.

In case no dns object is linked to the upstream and the host is a FQDN, then the system DNS will be used to resolve the upstream address.

Health Check

The upstreams may be configured to be subject to active health checks in order to monitor their readiness to receive traffic. Lobby will remove upstreams from the upstream group while they're unavailable and will be ensuring that the available upstreams are part of the respective upstream group.

Definition Description
protocol network protocol to be used for probing
port network port to be used for probing
start_available if the upstream should be available or unavailable at start [true, false ]
probe probe settings object linked to the health check

The health checks will always be performed against the upstream host address. However, it is possible to specify a different port and protocol.

Health Check Probe Settings
Definition Description
check_interval frequency in seconds for the health check to occur
timeout seconds to wait for response before considered as failed check
success_count amount of successful checks before upstream is set as available


Lobby allows for upstream hosts to be configured as FQDN's. In order to resolve the FQDN's, a DNS object may be defined to specify which servers should be used to resolve the FQDN.

It is also possible to overwrite the DNS Time-to-Live (TTL) field.

Definition Description
servers list of DNS addresses
ttl frequency in seconds for the name resolution to occur

The FQDN name resolution will be performed by the first DNS address on the servers list. If it fails, the next DNS address in the list will be attempted and so on, until the name has been successfuly resolved or the DNS addresses exhasuted.

In case the servers are not defined, the Lobby system host DNS addresses will be used.

In case the ttl is not defined, the TTL received on the name resolution will be used.

In a scenario where a FQDN has been previously resolved to an IP address, but that later the DNS stops resolving the FQDN, then Lobby will keep the last known IP address instead of making the upstream unavailable.

Config File Representation

A YAML file is used to set the Lobby configuration in accordance to the features discription above. The format can be consulted in the configuration or tutorials pages.

Feature Set

A summary of the Lobby feature set may be found below.

Feel free to reach out in case you wish any of the feature development to be prioritized.

Internet Protocols

Protocol Implemented
IPv4 v0.1.0

Traffic Protocols

Protocol Implemented
TCP v0.1.0

Load Balancing Modes

Mode Implemented
round-robin v0.1.0

Upstream Health Check

Feature Implemented
TCP v0.1.0
Start available v0.1.0
Start unavailable v0.1.0
Probe timeout v0.1.0
Probe check interval v0.1.0
Probe healthy threshold v0.1.0
Probe unhealthy threshold

Upstream Name Resolution

Feature Implemented
Upstream FQDN address v0.1.0
DNS backup v0.1.0
DNS Load Balancing
Host System DNS v0.1.0
Overwrite DNS TTL v0.1.0


Feature Implemented
YAML file based config v0.1.0
Hot config reload v0.1.0
API based config
Event triggers (ie alert)
Traffic mirroring
Metrics exposure
Prometheus endpoints
Graphical User Interface
systemd service


Other features and ideas for possible future implementation:

Feature Description
Target IP Range Load balance on received IP range
Target Interface Load balance on received interface
Packet Acceleration Software and Hardware packet routing acceleration
IPv4 to IPv6 Proxy from IPv4 targets to IPv6 upstreams
IPv6 to IPv4 Proxy from IPv6 targets to IPv4 upstreams
Rate limits Define traffic rating limits per target or upstream
Source IP allowed list Only allow traffic from allowed listed IP addresses
Source IP block list Drop traffic from block listed IP addresses
Lobby clustering Lobby cluster coordination
Kubernetes agent Configure Lobby based on Kubernetes services
Define Source address Allow Lobby IP address to upstreams to be configured
Local traffic Load Balancing Load balance locally generated traffic
Configurable nftables priority Load balance locally generated traffic