KittUnderlay Routing Fabric

The KittUnderlay Routing Fabric (WIP Draft)

Introduction

KittUnderlay is a work-in-progress routing architecture designed to explore a secure, scalable, and structured foundation for internal network routing. Built on iBGP mesh with WireGuard-based transport, the underlay ensures reliable connectivity between all nodes while maintaining simplicity and clarity.

Project Vision

The underlay architecture demonstrates that complex routing designs can remain understandable when responsibilities are clearly separated. Instead of overloading the network with unnecessary abstractions, the architecture applies each technology where it makes the most sense. Loopback addresses are distributed using standard iBGP, ensuring simplicity and universal reachability.

Where beneficial, the system introduces controlled dynamism—such as latency-informed MED adjustments—to improve path selection without sacrificing predictability.

As the network scales, Route Reflectors are introduced to optimize control-plane efficiency while maintaining consistent route visibility.

Key Goals

Maintain a clean and deterministic iBGP control plane
Use WireGuard for secure and flexible node-to-node connectivity
Keep loopback routing simple and label-free
Enable scalable growth through Route Reflectors
Preserve clarity between underlay, overlay, and service layers

Architecture Overview

Full iBGP Mesh (Initial Phase)
Every node peers directly with their adjacent neighbors using Link-Local IPv6, allowing straightforward route propagation and easier troubleshooting during early stages.

  graph LR

%% Center node
RR["Route Reflectors"]

%% Surrounding routers
R1["R1"]
R2["R2"]
R3["R3"]

%% iBGP (hub-and-spoke)
RR <-. "multiHop iBGP" .-> R1
RR <-. "multiHop iBGP" .-> R2
RR <-. "multiHop iBGP" .-> R3

%% Underlay (mesh between routers)
R1 <== "iBGP" ==> R2
R2 <== "iBGP" ==> R3
R3 <== "iBGP" ==> R1

WireGuard Underlay
All non-physical BGP sessions operate over WireGuard tunnels, providing encrypted transport independent of physical infrastructure. All tunnels configured with a unique peer where AllowedIPs = 0.0.0.0/0, ::0/0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[NetDev]
Kind=wireguard
Name=<IFNAME>

[WireGuard]
ListenPort=<ListenPort>
PrivateKeyFile=/run/secrets/wireguard_serverkey

[WireGuardPeer]
AllowedIPs=0.0.0.0/0
AllowedIPs=::/0
PersistentKeepalive=10
PublicKey=<PeerKey>

Loopback Announcements
Loopback interfaces are advertised via iBGP without MPLS labels. These addresses serve as stable router identifiers and core reachability endpoints across the fabric.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
template bgp kittunderlay {
  local port 1790;
  neighbor port 1790;
  rr client;
  path metric off;
  ipv4 {
    extended next hop;
    next hop self;
    import keep filtered;
    import filter {
      if is_valid4_loopback() then {
        if defined( bgp_med ) then
          bgp_med = bgp_med + 2147483648;
        else {
          bgp_med = 2147483648;
        }
        accept;
      } else reject;
    };
    export filter { if is_valid4_loopback() && source ~ [RTS_STATIC, RTS_DEVICE, RTS_BGP, RTS_OSPF] then accept; else reject; };
    import limit 1000 action block;
  };
  ipv6 {
    next hop self;
    import keep filtered;
    import filter {
      if is_valid6_loopback() then {
        if defined( bgp_med ) then
          bgp_med = bgp_med + 2147483648;
        else {
          bgp_med = 2147483648;
        }
        accept;
      } else reject;
    };
    export filter { if is_valid6_loopback() && source ~ [RTS_STATIC, RTS_DEVICE, RTS_BGP, RTS_OSPF] then accept; else reject; };
    import limit 1000 action block;
  };
}

Route Reflectors (Scaling Phase)
As the topology expands, Route Reflectors reduce the number of iBGP sessions required while preserving full route distribution across the network.
Adaptive Path Selection (Latency-Aware MED) A lightweight Go-based service runs alongside each node, continuously measuring latency between BGP peers over the WireGuard underlay. Based on observed performance, it dynamically adjusts BGP MED (Multi-Exit Discriminator) values to influence path selection, allowing the fabric to react to changing network conditions without manual intervention.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# <IFNAME>
# L: AS4242421945 | R: AS4242421945
protocol bgp <IFNAME> from kittunderlay {
  # disabled;
  local as 4242421945; # localIP: ""
  neighbor fe80::xxxx as 4242421945;
  interface "<IFNAME>";
  direct;
  ipv4 {
    import filter {
      if ( is_valid4_loopback() ) then {
        if defined( bgp_med ) then
          bgp_med = bgp_med + autoMED_<IFNAME>;
        else {
          bgp_med = autoMED_<IFNAME>;
        }
        accept;
      }
      reject;
    };
  };
  ipv6 {
    import filter {
      if ( is_valid6_loopback() ) then {
        if defined( bgp_med ) then
          bgp_med = bgp_med + autoMED_<IFNAME>;
        else {
          bgp_med = autoMED_<IFNAME>;
        }
        accept;
      }
      reject;
    };
  };
}

Features

✅ Full iBGP mesh configuration templates
💭 Automated WireGuard tunnel deployment
✅ Route Reflector deployment models
⚒️ Observability and route inspection tooling
✅ NixOS friendly configurations
✅ Automated MED adjustment based on real-time network performance
💭 Policy controls to bound and stabilize dynamic routing decisions

(Planned 💭 - In Progress ⚒️ - Done ✅)

Current Status

KittUnderlay is actively under development. Current efforts focus on stabilizing the interaction between the WireGuard underlay and iBGP control plane. Also we need to find a way to have different routing views using VRFs / PBR.

Route Reflector behavior and scaling patterns are being tested in parallel.

Getting Started

Planned documentation will include:

Building a WireGuard full mesh underlay
Establishing iBGP sessions across all nodes
Advertising loopbacks without MPLS
Transitioning from full mesh to Route Reflector topology

The objective is to provide a progressive learning path—from simple full-mesh routing to a more scalable, production-like design.

KittUnderlay is about building a strong foundation and applying the right level of complexity in the right place, keeping the network both powerful and understandable.