gredist: userspace GRE distribution

Normal load balancers usually have a port, protocol session or application request to work with.

GRE has none of those.

GRE is IP Protocol 47. There is no TCP or UDP port to select and no HTTP request to inspect.

gredist receives GRE traffic on a frontend address, selects a healthy backend deterministically, rebuilds the outer IP envelope where necessary and forwards the original GRE header and encapsulated payload unchanged.

frontend=217.155.241.55
backend=172.16.10.10
backend=172.16.10.11

IPv6 uses exactly the same configuration model:

frontend=2a02:8012:bc57::47
backend=2a02:8012:bc57:100::10
backend=2a02:8012:bc57:100::11

Pools may also mix address families. When the frontend and backend families differ, gredist terminates the outer IP envelope and constructs a new one for the backend. The GRE header and encapsulated traffic remain untouched.

Each service has exactly one frontend and one or more backends.

GRE distribution is one of those networking capabilities that is often absent entirely or appears only in expensive appliance tiers and licence upgrades.

Saphira needed it, so Saphira built it.

gredist is small C11 userspace software, supplied with its configuration, man page, test tools and lab harness. Like proxyto, it is designed to do one networking job and do it without dragging an entire platform behind it.

Production and commercial use as part of Saphira Linux is free under the Saphira BUSL-1.1 Additional Use Grant.

• No per-throughput licence.
• No feature unlock.
• No Protocol-47 tax.

gredist uses highest-random-weight rendezvous hashing.

The flow identity is derived from the outer source address and, where present, the GRE key. Each healthy backend receives a deterministic score and the highest-scoring backend wins.

That gives useful stability when the pool changes:

• removing a backend moves only the flows that selected it;
• surviving backend mappings remain stable;
• a recovered backend rejoins deterministically;
• keyed GRE tunnels naturally contribute their key to affinity.

The GRE key is a tunnel identifier, not a secret.

Backends are actively checked with ICMP every two seconds.

Two consecutive failures mark a backend down. Two consecutive successes bring it back up. State transitions are logged.

If no healthy backend remains, traffic is dropped rather than silently sent somewhere inappropriate.

Fail closed means fail closed.

GRE parsing follows the behaviour required by the Linux GRE interface while remaining an independent userspace implementation.

Malformed or unsafe input is rejected rather than guessed at. Tests cover conditions including:

• truncated packets;
• malformed GRE headers;
• fragments;
• oversized input;
• queue pressure;
• keyed and keyless GRE;
• IPv4 and IPv6;
• mixed-family forwarding;
• backend removal and recovery;
• affinity through pool changes.

The optional nftables fast path is intended for suitable same-family flows while the userspace path remains authoritative for the general case.

GRE provides encapsulation, not encryption.

Saphira packages strongSwan 6.1.0 alongside gredist so the two jobs can remain separate:

encrypted IPsec
      ↓
strongSwan / XFRM
      ↓
inner GRE
      ↓
gredist
      ↓
backend pool

The IPsec edge owns encryption and keys. gredist owns GRE distribution. Backends do not need to know how the encrypted outer transport arrived.

Both strongSwan and the current gredist revision are awaiting their first/current hatched publication wave, and the packages page shows that state directly.

• Live recipe and hatched build state

Three binaries are supplied:

gredist     distributor
gre-send    lab traffic generator
gre-sink    lab receiver

A named service reads its configuration from /etc/saphira/gredist/<service>.conf.

gredist service_name
gredist -c /path/to.conf
gredist --syslog service_name

SIGHUP   reload configuration
SIGUSR1  dump statistics
SIGTERM  terminate
SIGINT   terminate

Raw Protocol 47 sockets require the appropriate privileges, normally including CAP_NET_RAW and, depending on configuration, CAP_NET_ADMIN.

Logs go to stderr unless --syslog is selected.

The accompanying lab harness exercises real networking behaviour rather than merely unit-testing parser functions.

Coverage includes IPv4, IPv6 and mixed-family topologies, keyed and keyless GRE, backend removal and recovery, rapid flapping, malformed packets, oversized packets, fragmentation, loss, queue pressure and affinity.

run-tests.sh provides unit and integration coverage without requiring the full network-namespace lab.

The remaining beta gate is deliberate: raw-socket, network-namespace and OVS testing must pass to the project's satisfaction before the beta label disappears.

gredist 0.1.0-r3 is built and staged.

The currently installable hatched version remains r1 until the staged revision is published. Saphira exposes that difference on the packages page rather than pretending the recipe and live repository are always at the same revision.

Until the remaining lab proof is complete, treat gredist as working beta software for testing and evaluation, not as a production recommendation.

• Back to the load-balancing map
• Live recipe and hatched build state

The current saphira-gredist tree is Saphira-original userspace software licensed under BUSL-1.1.

Earlier Linux GRE source files retained in the recipe tree purely as development references have been removed; they were never built into gredist.

Under Saphira's Additional Use Grant, production and commercial use of gredist as part of Saphira Linux is free.

The licence automatically transitions to GPL-2.0-or-later according to the stated Change Date / BUSL terms.

• How Saphira software is licensed