src/plugins/srv6-am/am_plugin_doc.md

   1 # SRv6 endpoint to SR-unaware appliance via masquerading (End.AM) {#srv6_am_plugin_doc}
   2
   3 The masquerading proxy is an SR endpoint behavior for processing SRv6 traffic on
   4 behalf of an SR-unaware SF. This proxy thus receives SR traffic that is formed
   5 of an IPv6 header and an SRH on top of an inner payload. The masquerading
   6 behavior is independent from the inner payload type. Hence, the inner payload
   7 can be of any type but it is usually expected to be a transport layer packet,
   8 such as TCP or UDP.
   9
  10 A masquerading SR proxy segment is associated with the following mandatory
  11 parameters:
  12
  13 - S-ADDR: Ethernet or IPv6 address of the SF
  14 - IFACE-OUT: Local interface for sending traffic towards the SF
  15 - IFACE-IN: Local interface receiving the traffic coming back from the SF
  16
  17 A masquerading SR proxy segment is thus defined for a specific SF and bound to a
  18 pair of directed interfaces or sub-interfaces on the proxy. As opposed to the
  19 static and dynamic SR proxies, a masquerading segment can be present at the same
  20 time in any number of SR SC policies and the same interfaces can be bound to
  21 multiple masquerading proxy segments. The only restriction is that a
  22 masquerading proxy segment cannot be the last segment in an SR SC policy.
  23
  24 The first part of the masquerading behavior is triggered when the proxy node
  25 receives an IPv6 packet whose Destination Address matches a masquerading proxy
  26 segment. The proxy inspects the IPv6 extension headers and substitutes the
  27 Destination Address with the last segment in the SRH attached to the IPv6
  28 header, which represents the final destination of the IPv6 packet. The packet is
  29 then sent out towards the SF.
  30
  31 The SF receives an IPv6 packet whose source and destination addresses are
  32 respectively the original source and final destination. It does not attempt to
  33 inspect the SRH, as RFC8200 specifies that routing extension headers are not
  34 examined or processed by transit nodes. Instead, the SF simply forwards the
  35 packet based on its current Destination Address. In this scenario, we assume
  36 that the SF can only inspect, drop or perform limited changes to the packets.
  37 For example, Intrusion Detection Systems, Deep Packet Inspectors and non-NAT
  38 Firewalls are among the SFs that can be supported by a masquerading SR proxy.
  39
  40 The second part of the masquerading behavior, also called de- masquerading, is
  41 an inbound policy attached to the proxy interface receiving the traffic
  42 returning from the SF, IFACE-IN. This policy inspects the incoming traffic and
  43 triggers a regular SRv6 endpoint processing (End) on any IPv6 packet that
  44 contains an SRH. This processing occurs before any lookup on the packet
  45 Destination Address is performed and it is sufficient to restore the right
  46 active segment as the Destination Address of the IPv6 packet.
  47
  48 For more information, please see
  49 [draft-xuclad-spring-sr-service-chaining](https://datatracker.ietf.org/doc/draft-xuclad-spring-sr-service-chaining/).
  50
  51 ## CLI configuration
  52
  53 The following command instantiates a new End.AM segment that sends masqueraded
  54 traffic on interface `IFACE-OUT` towards an appliance at address `S-ADDR` and
  55 restores the active segment in the IPv6 header of the packets coming back on
  56 interface `IFACE-IN`.
  57
  58 ```
  59 sr localsid address SID behavior end.am nh S-ADDR oif IFACE-OUT iif IFACE-IN
  60 ```
  61
  62 For example, the below command configures the SID `1::A1` with an End.AM
  63 function for sending traffic on interface `GigabitEthernet0/8/0` to the
  64 appliance at address `A1::`, and receiving it back on interface
  65 `GigabitEthernet0/9/0`.
  66
  67 ```
  68 sr localsid address 1::A1 behavior end.am nh A1:: oif GigabitEthernet0/8/0 iif GigabitEthernet0/9/0
  69 ```
  70
  71 ## Pseudocode
  72
  73 ### Masquerading
  74
  75 Upon receiving a packet destined for S, where S is an IPv6 masquerading proxy
  76 segment, a node N processes it as follows.
  77
  78 ```
  79 IF NH=SRH & SL > 0 THEN
  80     Update the IPv6 DA with SRH[0]
  81     Forward the packet on IFACE-OUT
  82 ELSE
  83     Drop the packet
  84 ```
  85
  86 ### De-masquerading
  87
  88 Upon receiving a non-link-local IPv6 packet on IFACE-IN, a node N processes it
  89 as follows.
  90
  91 ```
  92 IF NH=SRH & SL > 0 THEN
  93     Decrement SL
  94     Update the IPv6 DA with SRH[SL]                             ;; Ref1
  95     Lookup DA in appropriate table and proceed accordingly
  96 ```
  97
  98 **Ref1:** This pseudocode can be augmented to support the Penultimate Segment
  99 Popping (PSP) endpoint flavor. The exact pseudocode modification are provided in
 100 [draft-filsfils-spring-srv6-network-programming](https://datatracker.ietf.org/doc/draft-filsfils-spring-srv6-network-programming/).