Add CIDR prefix VIP support in BPF datapath

Summary:
Add vip_lpm_map (BPF_MAP_TYPE_LPM_TRIE) for prefix-based VIP lookup,
gated behind CIDR_VIP_LOOKUP macro. When a packet's destination IPv6
address misses exact-match vip_map, the datapath falls back to LPM
trie lookup before trying port=0 wildcard.

- balancer_consts.h: MAX_LPM_VIPS, LPM_VIP_CNTR
- balancer_maps.h: vip_lpm_map definition
- balancer.bpf.c: LPM fallback in process_packet()
- BUCK: cidr_vip_lookup_gue BPF flavor
- Test fixtures and provision for CIDR VIP BPF tests

Reviewed By: avasylev

Differential Revision: D100089958

fbshipit-source-id: c218abc9006a593beb2d3bd09002469151922a7b

Author: Fei Chen

katran/lib/KatranLb.cpp

@@ -1021,6 +1021,13 @@ bool KatranLb::addVip(const VipKey& vip, const uint32_t flags) {
     LOG(ERROR) << "Invalid Vip address: " << vip.address;
     return false;
   }
+  if (vip.cidrVipPrefixLen > 0) {
+    if (!folly::IPAddress::validate(vip.address) ||
+        !folly::IPAddress(vip.address).isV6()) {
+      LOG(ERROR) << "CIDR VIP only supported for IPv6, got: " << vip.address;
+      return false;
+    }
+  }
   VLOG(1) << fmt::format(
       "adding new vip: {}:{}:{}", vip.address, vip.port, vip.proto);
 
@@ -1040,7 +1047,11 @@ bool KatranLb::addVip(const VipKey& vip, const uint32_t flags) {
     vip_meta meta;
     meta.vip_num = vip_num;
     meta.flags = flags;
-    updateVipMap(ModifyAction::ADD, vip, &meta);
+    if (vip.cidrVipPrefixLen > 0) {
+      updateVipLpmMap(ModifyAction::ADD, vip, &meta);
+    } else {
+      updateVipMap(ModifyAction::ADD, vip, &meta);
+    }
   }
   return true;
 }
@@ -1102,7 +1113,13 @@ bool KatranLb::delVip(const VipKey& vip) {
   }
   vipNums_.push_back(vip_iter->second.getVipNum());
   if (!config_.testing) {
-    updateVipMap(ModifyAction::DEL, vip);
+    // Use the stored key which has cidrVipPrefixLen from addVip
+    const auto& storedVipKey = vip_iter->first;
+    if (storedVipKey.cidrVipPrefixLen > 0) {
+      updateVipLpmMap(ModifyAction::DEL, storedVipKey);
+    } else {
+      updateVipMap(ModifyAction::DEL, storedVipKey);
+    }
   }
   vips_.erase(vip_iter);
   return true;
@@ -1169,7 +1186,11 @@ bool KatranLb::modifyVip(const VipKey& vip, uint32_t flag, bool set) {
     vip_meta meta;
     meta.vip_num = vip_iter->second.getVipNum();
     meta.flags = vip_iter->second.getVipFlags();
-    return updateVipMap(ModifyAction::ADD, vip, &meta);
+    const auto& storedVipKey = vip_iter->first;
+    if (storedVipKey.cidrVipPrefixLen > 0) {
+      return updateVipLpmMap(ModifyAction::ADD, storedVipKey, &meta);
+    }
+    return updateVipMap(ModifyAction::ADD, storedVipKey, &meta);
   }
   return true;
 }
@@ -3078,6 +3099,42 @@ bool KatranLb::updateVipMap(
   return true;
 }
 
+bool KatranLb::updateVipLpmMap(
+    const ModifyAction action,
+    const VipKey& vip,
+    vip_meta* meta) {
+  auto vip_addr = IpHelpers::parseAddrToBe(vip.address);
+  if ((vip_addr.flags & V6DADDR) == 0) {
+    LOG(ERROR) << "LPM VIP only supported for IPv6, got: " << vip.address;
+    lbStats_.bpfFailedCalls++;
+    return false;
+  }
+  v6_lpm_key lpm_key = {};
+  lpm_key.prefixlen = vip.cidrVipPrefixLen;
+  std::memcpy(lpm_key.addr, vip_addr.v6daddr, 16);
+
+  if (action == ModifyAction::ADD) {
+    auto res = bpfAdapter_->bpfUpdateMap(
+        bpfAdapter_->getMapFdByName(KatranLbMaps::vip_lpm_map), &lpm_key, meta);
+    if (res != 0) {
+      LOG(ERROR) << "can't add element to vip_lpm_map, error: "
+                 << folly::errnoStr(errno);
+      lbStats_.bpfFailedCalls++;
+      return false;
+    }
+  } else {
+    auto res = bpfAdapter_->bpfMapDeleteElement(
+        bpfAdapter_->getMapFdByName(KatranLbMaps::vip_lpm_map), &lpm_key);
+    if (res != 0) {
+      LOG(ERROR) << "can't delete element from vip_lpm_map, error: "
+                 << folly::errnoStr(errno);
+      lbStats_.bpfFailedCalls++;
+      return false;
+    }
+  }
+  return true;
+}
+
 bool KatranLb::updateHcKeyMap(
     const ModifyAction action,
     const VipKey& hcKey,

katran/lib/KatranLb.h

@@ -135,6 +135,7 @@ constexpr auto per_hckey_stats = "per_hckey_stats";
 constexpr auto reals = "reals";
 constexpr auto server_id_map = "server_id_map";
 constexpr auto stats = "stats";
+constexpr auto vip_lpm_map = "vip_lpm_map";
 constexpr auto vip_map = "vip_map";
 constexpr auto vip_miss_stats = "vip_miss_stats";
 constexpr auto vip_to_down_reals_map = "vip_to_down_reals_map";
@@ -1131,6 +1132,14 @@ class KatranLb {
       const VipKey& vip,
       vip_meta* meta = nullptr);
 
+  /**
+   * update vip_lpm_map (add or remove prefix VIP) in forwarding plane
+   */
+  bool updateVipLpmMap(
+      const ModifyAction action,
+      const VipKey& vip,
+      vip_meta* meta = nullptr);
+
   /**
    * Update hc_key_map (add or delete) in healthchecking bpf program.
    */

katran/lib/KatranLbStructs.h

@@ -325,6 +325,11 @@ class VipKey {
   std::string address;
   uint16_t port;
   uint8_t proto;
+  // 0 = exact-match VIP (default). >0 = CIDR prefix VIP (e.g., 96 for /96).
+  // IPv6 only today. Must be greater than min_v6_prefix (currently 64).
+  // Not included in hash/equality — (address, port, proto) uniquely identifies
+  // a VIP. cidrVipPrefixLen is metadata carried alongside.
+  uint8_t cidrVipPrefixLen{0};
 
   bool operator==(const VipKey& other) const {
     return (

katran/lib/bpf/balancer.bpf.c

@@ -826,7 +826,19 @@ process_packet(struct xdp_md* xdp, __u64 nh_off, bool is_ipv6) {
     vip.port = 0;
     vip_info = bpf_map_lookup_elem(&vip_map, &vip);
     if (!vip_info) {
-      return XDP_PASS;
+#ifdef CIDR_VIP
+      // Fallback to LPM prefix-based VIP lookup (IPv6 only).
+      // LPM key has no port/proto, so one lookup is sufficient.
+      if (is_ipv6) {
+        struct v6_lpm_key lpm_key = {};
+        lpm_key.prefixlen = 128;
+        memcpy(lpm_key.addr, pckt.flow.dstv6, 16);
+        vip_info = bpf_map_lookup_elem(&vip_lpm_map, &lpm_key);
+      }
+#endif // CIDR_VIP
+      if (!vip_info) {
+        return XDP_PASS;
+      }
     }
 
     if (!(vip_info->flags & F_HASH_DPORT_ONLY) &&

katran/lib/bpf/balancer_consts.h

@@ -54,6 +54,19 @@
 #define MAX_VIPS 512
 #endif
 
+#ifndef MAX_CIDR_VIPS
+// MAX_CIDR_VIPS is the size of lpm trie map we use to sore meta info of cidr
+// vips while MAX_VIPS is used as the size of the regular vip_map for non-cidr
+// vips.
+// For now, we still use MAX_VIPS for the total max number of vips
+// including both non-cidr and cidr vips. CH_RING and stats maps are
+// still using MAX_VIPS as the max size used by both cidr and non-cidr vips
+// meanwhile.
+// TODO: we need a separate macro for the size of non-cidr vips to avoid
+// the confusion while MAX_VIP is the sum of non-cidr and cidr vips.
+#define MAX_CIDR_VIPS 256
+#endif
+
 // 1 real is equal to 1 ip address. so server w/ v4 and v6 would most likely
 // consume 2 spots
 #ifndef MAX_REALS
@@ -297,6 +310,7 @@ v2 tracks misses for TCP non syns */
 #define XDP_PASS_CNTR 19 // packets passed up to the kernel
 // Tracks successful egress decap packets (XDP_TX after GUE decap)
 #define EGRESS_DECAP_CNTR 20
+#define LPM_VIP_CNTR 21 // packets matched via LPM prefix VIP lookup
 
 // indice for all stats maps defined above correspond to entries in the map
 // stats starting from the index MAX_VIPS. The max_entries of stats is

katran/lib/bpf/balancer_maps.h

@@ -37,6 +37,19 @@ struct {
   __uint(map_flags, NO_FLAGS);
 } vip_map SEC(".maps");
 
+#ifdef CIDR_VIP
+// map for prefix-based VIP lookup (IPv6 /96 prefix VIPs).
+// packets whose destination IPv6 address matches a prefix in this map
+// are load-balanced the same as exact-match VIPs.
+struct {
+  __uint(type, BPF_MAP_TYPE_LPM_TRIE);
+  __type(key, struct v6_lpm_key);
+  __type(value, struct vip_meta);
+  __uint(max_entries, MAX_CIDR_VIPS);
+  __uint(map_flags, BPF_F_NO_PREALLOC);
+} vip_lpm_map SEC(".maps");
+#endif // CIDR_VIP
+
 // fallback lru. we should never hit this one outside of unittests
 struct {
   __uint(type, BPF_MAP_TYPE_LRU_HASH);

katran/lib/testing/fixtures/KatranCidrVipTestFixtures.h

@@ -0,0 +1,122 @@
+// clang-format off
+
+/* Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#pragma once
+#include <string>
+#include <vector>
+#include "katran/lib/testing/tools/PacketAttributes.h"
+#include "katran/lib/testing/tools/PacketBuilder.h"
+
+namespace katran {
+namespace testing {
+/**
+ * Test fixtures for CIDR_VIP feature.
+ *
+ * This feature enables prefix-based VIP matching using an LPM trie. When a
+ * packet's destination IPv6 address does not match any exact VIP in vip_map,
+ * the datapath falls back to vip_lpm_map for prefix-based matching.
+ *
+ * Setup: A /96 CIDR VIP is added at fc00:1::/96 with reals fc00::1 and fc00::2.
+ * Packets to any address in fc00:1::0/96 (e.g., fc00:1::100, fc00:1::200)
+ * should match the CIDR VIP and be load-balanced to a real.
+ *
+ * Test cases cover:
+ * - IPv6 TCP packet matching CIDR VIP prefix (different IPs in /96 range)
+ * - IPv6 UDP packet matching CIDR VIP prefix
+ * - IPv6 packet NOT matching any prefix (XDP_PASS)
+ * - IPv4 packet should not match CIDR VIP (IPv6 only)
+ *
+ * Note: These fixtures use GUE encapsulation.
+ */
+const std::vector<::katran::PacketAttributes> cidrVipTestFixtures = {
+    // 1
+    // ipv6 TCP: dst fc00:1::100 matches CIDR VIP fc00:1::/96 (port=0 means
+    // all ports). Routes to real fc00::1 via GUE encap.
+    {.description = "ipv6 tcp: CIDR VIP match. CIDR_VIP is required",
+     .expectedReturnValue = "XDP_TX",
+     .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("0x1", "0x2")
+         .IPv6("fc00:2::1", "fc00:1::100")
+         .TCP(31337, 80, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt"),
+     .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("02:00:00:00:00:00", "00:00:de:ad:be:af")
+         .IPv6("fc00:2307::1337", "fc00::1", 64, 0, 0)
+         .UDP(31337, 9886)
+         .IPv6("fc00:2::1", "fc00:1::100")
+         .TCP(31337, 80, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt")
+    },
+    // 2
+    // ipv6 TCP: dst fc00:1::200 also matches CIDR VIP fc00:1::/96 (port=0
+    // means all ports). Different dest IP in same /96, should match same VIP.
+    {.description = "ipv6 tcp: CIDR VIP match different IP in range. CIDR_VIP is required",
+     .expectedReturnValue = "XDP_TX",
+     .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("0x1", "0x2")
+         .IPv6("fc00:2::1", "fc00:1::200")
+         .TCP(31337, 443, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt"),
+     .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("02:00:00:00:00:00", "00:00:de:ad:be:af")
+         .IPv6("fc00:2307::1337", "fc00::1", 64, 0, 0)
+         .UDP(31337, 9886)
+         .IPv6("fc00:2::1", "fc00:1::200")
+         .TCP(31337, 443, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt")
+    },
+    // 3
+    // ipv6 TCP: dst fc00:1::400 with a different port (8080) matches
+    // CIDR VIP fc00:1::/96 (port=0 means all ports).
+    // Packet misses vip_map (exact port), misses vip_map (port=0),
+    // then hits LPM trie.
+    {.description = "ipv6 tcp: CIDR VIP match on different port. CIDR_VIP is required",
+     .expectedReturnValue = "XDP_TX",
+     .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("0x1", "0x2")
+         .IPv6("fc00:2::1", "fc00:1::400")
+         .TCP(31337, 8080, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt"),
+     .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("02:00:00:00:00:00", "00:00:de:ad:be:af")
+         .IPv6("fc00:2307::1337", "fc00::1", 64, 0, 0)
+         .UDP(31337, 9886)
+         .IPv6("fc00:2::1", "fc00:1::400")
+         .TCP(31337, 8080, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt")
+    },
+    // 4
+    // ipv6: dst fc00:3::1 does NOT match CIDR VIP fc00:1::/96 (port=0 means
+    // all ports, but prefix doesn't match). Should be passed to kernel stack.
+    {.description = "ipv6: CIDR VIP miss. CIDR_VIP is required",
+     .expectedReturnValue = "XDP_PASS",
+     .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("0x1", "0x2")
+         .IPv6("fc00:2::1", "fc00:3::1")
+         .TCP(31337, 80, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt"),
+     .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+         .Eth("0x1", "0x2")
+         .IPv6("fc00:2::1", "fc00:3::1")
+         .TCP(31337, 80, 0, 0, 8192, TH_ACK)
+         .payload("katran test pkt")
+    },
+};
+
+} // namespace testing
+} // namespace katran

katran/lib/testing/utils/KatranTestProvision.cpp

@@ -229,6 +229,17 @@ void prepareOptionalLbData(katran::KatranLb& lb) {
   lb.modifyReal("10.0.0.6", kLocalReal);
 }
 
+void prepareCidrVipLbData(katran::KatranLb& lb) {
+  katran::VipKey vip;
+  // adding a /96 CIDR VIP for testing prefix-based VIP matching
+  vip.address = "fc00:1::";
+  vip.port = 0;
+  vip.proto = kTcp;
+  vip.cidrVipPrefixLen = 96;
+  lb.addVip(vip);
+  addReals(lb, vip, {"fc00::1", "fc00::2"});
+}
+
 void prepareLbDataStableRt(katran::KatranLb& lb) {
   lb.restartKatranMonitor(kMonitorLimit);
   katran::VipKey vip;

katran/lib/testing/utils/KatranTestProvision.h

@@ -180,6 +180,8 @@ void prepareLbData(katran::KatranLb& lb, bool skipLru = false);
 
 void prepareOptionalLbData(katran::KatranLb& lb);
 
+void prepareCidrVipLbData(katran::KatranLb& lb);
+
 void prepareLbDataStableRt(katran::KatranLb& lb);
 
 void prepareLbDataXpopDecap(katran::KatranLb& lb);

katran/lib/tests/KatranLbTest.cpp

@@ -159,6 +159,40 @@ TEST_F(KatranLbTest, testAddingInvalidVip) {
   ASSERT_FALSE(lb->addVip(v));
 };
 
+TEST_F(KatranLbTest, testCidrVipAddDelete) {
+  VipKey v;
+  v.address = "fc00::1";
+  v.port = 0;
+  v.proto = 6;
+  v.cidrVipPrefixLen = 96;
+  // adding and deleting a CIDR VIP
+  ASSERT_TRUE(lb->addVip(v));
+  ASSERT_TRUE(lb->delVip(v));
+};
+
+TEST_F(KatranLbTest, testCidrVipInvalidIpv4) {
+  VipKey v;
+  v.address = "192.168.1.1";
+  v.port = 0;
+  v.proto = 6;
+  v.cidrVipPrefixLen = 96;
+  // CIDR VIP with IPv4 address should fail
+  ASSERT_FALSE(lb->addVip(v));
+};
+
+TEST_F(KatranLbTest, testCidrVipModify) {
+  VipKey v;
+  v.address = "fc00::1";
+  v.port = 0;
+  v.proto = 6;
+  v.cidrVipPrefixLen = 96;
+  ASSERT_TRUE(lb->addVip(v));
+  // modifying flags on a CIDR VIP
+  ASSERT_TRUE(lb->modifyVip(v, 1, true));
+  ASSERT_EQ(lb->getVipFlags(v), 1);
+  ASSERT_TRUE(lb->delVip(v));
+};
+
 TEST_F(KatranLbTest, testRealHelpers) {
   lb->addVip(v1);