Add egress decap support: DECAP_EGRESS flag + XDP_TX path

Summary:
Add a third decap behavior to Katran's inline GUE decapsulation path
for egress DSR from cloud backends (EoPC).

Today, the `decap_dst` BPF map stores a `__u32 flags` value per
destination but the flags are never read — the code only checks key
existence. This diff activates the flags field:

- `flags = 0` (existing xpop behavior): GUE decap → recirculate
  through Katran for load-balancing the inner packet
- `flags = DECAP_EGRESS (0x2)` (new): GUE decap → MAC swap → XDP_TX
  directly out the NIC, used for egress DSR responses from cloud
  Revproxy that need to be forwarded to the client

BPF changes:
- `check_decap_dst()`: reads `decap_dst_flags` value and passes it
  to the caller via new `out_decap_flags` parameter
- `process_encaped_gue_pckt()`: new XDP_TX code path when
  `DECAP_EGRESS` flag is set — swaps src/dst MACs and returns XDP_TX
- New counter `EGRESS_DECAP_CNTR` (position 20) tracks egress decap
  packets (v1=IPv4 inner, v2=IPv6 inner)

Userspace changes:
- `addEgressDecapDst()`: public API that calls `modifyDecapDst()`
  with `DECAP_EGRESS` flag (vs `addInlineDecapDst()` which uses 0)
- `getEgressDecapStats()`: reads the new BPF counter

Reviewed By: frankfeir, nikhildl12

Differential Revision: D99473916

fbshipit-source-id: 7fe9b2fd945813a61595eec80f957850f656ef0b

Author: tagrawal03

katran/lib/KatranLb.cpp

@@ -1666,6 +1666,32 @@ bool KatranLb::addInlineDecapDst(const std::string& dst) {
   return true;
 }
 
+bool KatranLb::addEgressDecapDst(const std::string& dst) {
+  if (!features_.inlineDecap && !config_.testing) {
+    LOG(ERROR) << "inline decap is not enabled in forwarding plane";
+    return false;
+  }
+  if (validateAddress(dst) == AddressType::INVALID) {
+    LOG(ERROR) << "invalid egress decap destination address: " << dst;
+    return false;
+  }
+  folly::IPAddress daddr(dst);
+  if (decapDsts_.find(daddr) != decapDsts_.end()) {
+    LOG(ERROR) << "trying to add already existing egress decap dst";
+    return false;
+  }
+  if (decapDsts_.size() + 1 > config_.maxDecapDst) {
+    LOG(ERROR) << "size of decap destinations map is exhausted";
+    return false;
+  }
+  VLOG(2) << "adding egress decap dst " << dst;
+  decapDsts_.insert(daddr);
+  if (!config_.testing) {
+    modifyDecapDst(ModifyAction::ADD, daddr, kDecapEgress);
+  }
+  return true;
+}
+
 bool KatranLb::delInlineDecapDst(const std::string& dst) {
   if (!features_.inlineDecap && !config_.testing) {
     LOG(ERROR) << "source based routing is not enabled in forwarding plane";
@@ -2127,6 +2153,10 @@ lb_stats KatranLb::getXPopDecapSuccessfulStats() {
   return getLbStats(config_.maxVips + kXPopDecapSuccessfulOffset);
 }
 
+lb_stats KatranLb::getEgressDecapStats() {
+  return getLbStats(config_.maxVips + kEgressDecapOffset);
+}
+
 lb_stats KatranLb::getUdpFlowMigrationStats() {
   return getLbStats(config_.maxVips + kUdpFlowMigrationInvalidationOffset);
 }

katran/lib/KatranLb.h

@@ -74,6 +74,10 @@ constexpr uint32_t kXdpTotalOffset = 16;
 constexpr uint32_t kXdpTxOffset = 17;
 constexpr uint32_t kXdpDropOffset = 18;
 constexpr uint32_t kXdpPassOffset = 19;
+constexpr uint32_t kEgressDecapOffset = 20;
+
+// Flag value for egress decap destinations (must match DECAP_EGRESS in BPF)
+constexpr uint32_t kDecapEgress = 0x2;
 
 /**
  * LRU map related constants
@@ -431,6 +435,17 @@ class KatranLb {
    */
   bool addInlineDecapDst(const std::string& dst);
 
+  /**
+   * @param string address for egress decap (XDP_TX after GUE decap)
+   * @return bool true on success
+   *
+   * helper function to add address for egress decapsulation.
+   * packets arriving at this destination are GUE-decapped and
+   * XDP_TX'd directly (no recirculation), used for DSR egress
+   * from cloud backends.
+   */
+  bool addEgressDecapDst(const std::string& dst);
+
   /**
    * @param string address for inline decapsulation
    * @return bool true on success
@@ -659,6 +674,14 @@ class KatranLb {
    */
   lb_stats getXPopDecapSuccessfulStats();
 
+  /**
+   * @return struct lb_stats w/ statistics of egress decap packets
+   *
+   * helper function which returns how many packets were successfully
+   * egress-decapped (GUE decap + XDP_TX)
+   */
+  lb_stats getEgressDecapStats();
+
   /**
    * @return struct lb_stats w/ statistics of total invalidated dst
    *

katran/lib/bpf/balancer.bpf.c

@@ -200,8 +200,11 @@ __attribute__((__always_inline__)) static inline void connection_table_lookup(
 }
 
 #ifdef INLINE_DECAP_GENERIC
-__attribute__((__always_inline__)) static inline int
-check_decap_dst(struct packet_description* pckt, bool is_ipv6, bool* pass) {
+__attribute__((__always_inline__)) static inline int check_decap_dst(
+    struct packet_description* pckt,
+    bool is_ipv6,
+    bool* pass,
+    __u32* out_decap_flags) {
   struct address dst_addr = {};
   struct lb_stats* data_stats;
 
@@ -215,6 +218,7 @@ check_decap_dst(struct packet_description* pckt, bool is_ipv6, bool* pass) {
 
   if (decap_dst_flags) {
     *pass = false;
+    *out_decap_flags = *decap_dst_flags;
     __u32 stats_key = MAX_VIPS + REMOTE_ENCAP_CNTRS;
     data_stats = bpf_map_lookup_elem(&stats, &stats_key);
     if (!data_stats) {
@@ -435,7 +439,8 @@ __attribute__((__always_inline__)) static inline int process_encaped_gue_pckt(
     struct xdp_md* xdp,
     __u64 off,
     bool is_ipv6,
-    bool pass) {
+    bool pass,
+    __u32 decap_flags) {
   int offset = 0;
   int action;
   bool inner_ipv6 = false;
@@ -490,6 +495,35 @@ __attribute__((__always_inline__)) static inline int process_encaped_gue_pckt(
   if (action >= 0) {
     return action;
   }
+  if (!pass && (decap_flags & DECAP_EGRESS)) {
+    // Egress decap: decap complete, XDP_TX the inner packet directly.
+    // The inner packet is a DSR response (src=VIP, dst=client) that needs
+    // to be sent out the NIC toward the router for forwarding to the client.
+    void* eth_data = (void*)(long)xdp->data;
+    void* eth_data_end = (void*)(long)xdp->data_end;
+    struct ethhdr* eth = eth_data;
+    if ((void*)(eth + 1) > eth_data_end) {
+      return XDP_DROP;
+    }
+    // Swap MAC addresses: incoming packet has router MAC as src,
+    // our NIC MAC as dst. Swap so packet goes back to the router.
+    __u8 tmp_mac[ETH_ALEN];
+    __builtin_memcpy(tmp_mac, eth->h_dest, ETH_ALEN);
+    __builtin_memcpy(eth->h_dest, eth->h_source, ETH_ALEN);
+    __builtin_memcpy(eth->h_source, tmp_mac, ETH_ALEN);
+
+    __u32 egress_stats_key = MAX_VIPS + EGRESS_DECAP_CNTR;
+    struct lb_stats* egress_stats =
+        bpf_map_lookup_elem(&stats, &egress_stats_key);
+    if (egress_stats) {
+      if (inner_ipv6) {
+        egress_stats->v2 += 1;
+      } else {
+        egress_stats->v1 += 1;
+      }
+    }
+    return XDP_TX;
+  }
   if (pass) {
     // pass packet to kernel after decapsulation
     // increment stats after decapsulation
@@ -735,15 +769,17 @@ process_packet(struct xdp_md* xdp, __u64 nh_off, bool is_ipv6) {
    */
   if (protocol == IPPROTO_IPIP) {
     bool pass = true;
-    action = check_decap_dst(&pckt, is_ipv6, &pass);
+    __u32 decap_flags = 0;
+    action = check_decap_dst(&pckt, is_ipv6, &pass, &decap_flags);
     if (action >= 0) {
       return action;
     }
     return process_encaped_ipip_pckt(
         &data, &data_end, xdp, &is_ipv6, &protocol, pass);
   } else if (protocol == IPPROTO_IPV6) {
     bool pass = true;
-    action = check_decap_dst(&pckt, is_ipv6, &pass);
+    __u32 decap_flags = 0;
+    action = check_decap_dst(&pckt, is_ipv6, &pass, &decap_flags);
     if (action >= 0) {
       return action;
     }
@@ -763,12 +799,13 @@ process_packet(struct xdp_md* xdp, __u64 nh_off, bool is_ipv6) {
 #ifdef INLINE_DECAP_GUE
     if (pckt.flow.port16[1] == bpf_htons(GUE_DPORT)) {
       bool pass = true;
-      action = check_decap_dst(&pckt, is_ipv6, &pass);
+      __u32 decap_flags = 0;
+      action = check_decap_dst(&pckt, is_ipv6, &pass, &decap_flags);
       if (action >= 0) {
         return action;
       }
       return process_encaped_gue_pckt(
-          &data, &data_end, xdp, nh_off, is_ipv6, pass);
+          &data, &data_end, xdp, nh_off, is_ipv6, pass, decap_flags);
     }
 #endif // of INLINE_DECAP_GUE
   } else {

katran/lib/bpf/balancer_consts.h

@@ -255,6 +255,9 @@
 
 #define NO_FLAGS 0
 
+// flag for egress decap destinations (XDP_TX after decap, no recirculate)
+#define DECAP_EGRESS 0x2
+
 // offset of the lru cache hit related counters
 /* v1 tracks total vip packets (no longer used for lru calculations)
 v2 tracks lru misses */
@@ -292,6 +295,8 @@ v2 tracks misses for TCP non syns */
 #define XDP_TX_CNTR 17 // total packets sent to backend
 #define XDP_DROP_CNTR 18 // total packets dropped by katran
 #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
 
 // 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/testing/fixtures/KatranEgressDecapTestFixtures.h

@@ -0,0 +1,94 @@
+// 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 <vector>
+#include "katran/lib/testing/tools/PacketAttributes.h"
+#include "katran/lib/testing/tools/PacketBuilder.h"
+
+/**
+ * Test fixtures for egress decapsulation (XDP_TX after GUE decap).
+ *
+ * Unlike xpop decap which recirculates the inner packet through Katran,
+ * egress decap strips the GUE header, swaps MACs, and returns XDP_TX
+ * directly. Used for DSR egress from cloud backends (EoPC).
+ *
+ * Input packets: GUE-encapsulated to the egress decap VIP (fc00:1405::1).
+ * Expected output: inner packet with MACs swapped (dst=src, src=dst of input).
+ */
+
+namespace katran {
+namespace testing {
+
+const std::vector<::katran::PacketAttributes> egressDecapTestFixtures = {
+  //1: Egress decap IPv4 inner packet — XDP_TX with MAC swap
+  {
+    .description = "Egress decap: GUE IPv6->IPv4 inner, XDP_TX with MAC swap.",
+    .expectedReturnValue = "XDP_TX",
+    .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+        .Eth("0x1", "0x2")
+        .IPv6("100::64", "fc00:1405::1", 64)
+        .UDP(31337, 9886)
+        .IPv4("10.200.1.1", "192.168.1.3", 64)
+        .UDP(80, 31337)
+        .payload("egress decap test"),
+    // After decap: inner packet with MACs swapped (0x2 -> dst, 0x1 -> src)
+    .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+        .Eth("02:00:00:00:00:00", "01:00:00:00:00:00")
+        .IPv4("10.200.1.1", "192.168.1.3", 63, 0, 1)
+        .UDP(80, 31337)
+        .payload("egress decap test")
+  },
+  //2: Egress decap IPv6 inner packet — XDP_TX with MAC swap
+  {
+    .description = "Egress decap: GUE IPv6->IPv6 inner, XDP_TX with MAC swap.",
+    .expectedReturnValue = "XDP_TX",
+    .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+        .Eth("0x1", "0x2")
+        .IPv6("100::64", "fc00:1405::1", 64)
+        .UDP(31337, 9886)
+        .IPv6("fc00:1::1", "fc00:2307:1::2", 64)
+        .TCP(80, 31337, 0, 0, 8192, 0x10)
+        .payload("egress decap test"),
+    .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+        .Eth("02:00:00:00:00:00", "01:00:00:00:00:00")
+        .IPv6("fc00:1::1", "fc00:2307:1::2", 63)
+        .TCP(80, 31337, 0, 0, 8192, 0x10)
+        .payload("egress decap test")
+  },
+  //3: Egress decap with TTL expired — XDP_DROP
+  {
+    .description = "Egress decap: GUE IPv6->IPv4 inner with TTL expired, XDP_DROP.",
+    .expectedReturnValue = "XDP_DROP",
+    .inputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+        .Eth("0x1", "0x2")
+        .IPv6("100::64", "fc00:1405::1", 64)
+        .UDP(31337, 9886)
+        .IPv4("10.200.1.1", "192.168.1.3", 1)
+        .UDP(80, 31337)
+        .payload("egress decap test"),
+    .expectedOutputPacketBuilder = katran::testing::PacketBuilder::newPacket()
+        .Eth("01:00:00:00:00:00", "02:00:00:00:00:00")
+        .IPv4("10.200.1.1", "192.168.1.3", 0, 0, 1)
+        .UDP(80, 31337)
+        .payload("egress decap test")
+  },
+};
+
+} // namespace testing
+} // namespace katran

katran/lib/testing/framework/katran_tester.cpp

@@ -25,6 +25,7 @@
 #include <gflags/gflags.h>
 
 #include "katran/lib/MonitoringStructs.h"
+#include "katran/lib/testing/fixtures/KatranEgressDecapTestFixtures.h"
 #include "katran/lib/testing/fixtures/KatranHCTestFixtures.h"
 #include "katran/lib/testing/fixtures/KatranIcmpTooBigTestFixtures.h"
 #include "katran/lib/testing/fixtures/KatranLpmSrcLookupTestFixtures.h"
@@ -65,6 +66,7 @@ DEFINE_bool(
 DEFINE_bool(gue, false, "run GUE tests instead of IPIP ones");
 DEFINE_bool(stable_rt, false, "run UDP Stable Routing tests");
 DEFINE_bool(xpop_decap, false, "run cross pop decap tests");
+DEFINE_bool(egress_decap, false, "run egress decap tests");
 DEFINE_bool(udp_flow_migration, false, "run UDP flow migration tests");
 DEFINE_bool(
     tpr,
@@ -182,6 +184,14 @@ void runTestsFromFixture(
     auto xpopTestParams = createXPopDecapTestParam();
     testXPopDecapCounters(lb, xpopTestParams);
   }
+  if (FLAGS_egress_decap) {
+    prepareLbDataXpopDecap(lb);
+    prepareLbDataEgressDecap(lb);
+    tester.resetTestFixtures(katran::testing::egressDecapTestFixtures);
+    tester.testFromFixture();
+    auto egressTestParams = createEgressDecapTestParam();
+    testEgressDecapCounters(lb, egressTestParams);
+  }
   if (FLAGS_udp_flow_migration) {
     prepareUdpFlowMigrationTestData(lb);
     tester.resetTestFixtures(

katran/lib/testing/utils/KatranTestProvision.cpp

@@ -327,6 +327,12 @@ void prepareLbDataXpopDecap(katran::KatranLb& lb) {
   lb.addHealthcheckerDst(3, "fc00::1");
 }
 
+void prepareLbDataEgressDecap(katran::KatranLb& lb) {
+  // Use the same VIPs as xpop (already set up by prepareLbDataXpopDecap).
+  // Add an egress decap destination with DECAP_EGRESS flag.
+  lb.addEgressDecapDst("fc00:1405::1");
+}
+
 void prepareUdpFlowMigrationTestData(katran::KatranLb& lb) {
   lb.restartKatranMonitor(kMonitorLimit);
 
@@ -511,6 +517,15 @@ uint64_t KatranTestParam::expectedXPopDecapSuccessfulV6() noexcept {
 uint64_t KatranTestParam::expectedUdpFlowMigrationInvalidation() noexcept {
   return _lookup_counter(KatranTestCounters::UDP_FLOW_MIGRATION_STATS);
 }
+uint64_t KatranTestParam::expectedEgressDecapPkts() noexcept {
+  return _lookup_counter(KatranTestCounters::EGRESS_DECAP_PKTS);
+}
+uint64_t KatranTestParam::expectedEgressDecapPktsV4() noexcept {
+  return _lookup_counter(KatranTestCounters::EGRESS_DECAP_PKTS_V4);
+}
+uint64_t KatranTestParam::expectedEgressDecapPktsV6() noexcept {
+  return _lookup_counter(KatranTestCounters::EGRESS_DECAP_PKTS_V6);
+}
 uint64_t KatranTestParam::_lookup_counter(KatranTestCounters counter) noexcept {
   if (!expectedCounters.contains(counter)) {
     return 0;

katran/lib/testing/utils/KatranTestProvision.h

@@ -106,7 +106,11 @@ enum class KatranTestCounters : uint8_t {
   XPOP_DECAP_SUCCESSFUL_V4 = 27,
   XPOP_DECAP_SUCCESSFUL_V6 = 28,
   // udp flow migration counters
-  UDP_FLOW_MIGRATION_STATS = 29
+  UDP_FLOW_MIGRATION_STATS = 29,
+  // egress decap counters
+  EGRESS_DECAP_PKTS = 30,
+  EGRESS_DECAP_PKTS_V4 = 31,
+  EGRESS_DECAP_PKTS_V6 = 32
 };
 
 struct KatranTestParam {
@@ -146,6 +150,9 @@ struct KatranTestParam {
   uint64_t expectedXPopDecapSuccessfulV4() noexcept;
   uint64_t expectedXPopDecapSuccessfulV6() noexcept;
   uint64_t expectedUdpFlowMigrationInvalidation() noexcept;
+  uint64_t expectedEgressDecapPkts() noexcept;
+  uint64_t expectedEgressDecapPktsV4() noexcept;
+  uint64_t expectedEgressDecapPktsV6() noexcept;
 
   // helper method to lookup the expected counter value
   uint64_t _lookup_counter(KatranTestCounters counter) noexcept;
@@ -183,6 +190,8 @@ void preparePerfTestingLbData(katran::KatranLb& lb);
 
 void prepareUdpFlowMigrationTestData(katran::KatranLb& lb);
 
+void prepareLbDataEgressDecap(katran::KatranLb& lb);
+
 void setDownHostForUdpFlowMigration(katran::KatranLb& lb);
 } // namespace testing
 } // namespace katran